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

package/src/TrueSheet.types.ts

@@ -1,7 +1,11 @@
 import type { ComponentType, ReactElement } from 'react';
-import type { ColorValue, NativeSyntheticEvent, ViewProps } from 'react-native';
-
-import type { TrueSheetGrabberProps } from './TrueSheetGrabber';
+import type {
+  ColorValue,
+  NativeSyntheticEvent,
+  StyleProp,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
 
 export interface DetentInfoEventPayload {
   /**
@@ -12,14 +16,18 @@ export interface DetentInfoEventPayload {
    * The Y position of the sheet relative to the screen.
    */
   position: number;
+  /**
+   * The detent value (0-1) for the current index.
+   */
+  detent: number;
 }
 
 export interface PositionChangeEventPayload extends DetentInfoEventPayload {
   /**
-   * Workaround for cases where we can't get real-time position from native.
-   * When true, manually animate the position in JS.
+   * Indicates whether the position value is real-time (e.g., during drag or animation tracking).
+   * When false, the position should be animated in JS.
    */
-  transitioning: boolean;
+  realtime: boolean;
 }
 
 export type MountEvent = NativeSyntheticEvent<null>;
@@ -32,66 +40,298 @@ export type DragBeginEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type DragChangeEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type DragEndEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type PositionChangeEvent = NativeSyntheticEvent<PositionChangeEventPayload>;
+export type DidFocusEvent = NativeSyntheticEvent<null>;
+export type DidBlurEvent = NativeSyntheticEvent<null>;
+export type WillFocusEvent = NativeSyntheticEvent<null>;
+export type WillBlurEvent = NativeSyntheticEvent<null>;
+
+/**
+ * Options for customizing the grabber (drag handle) appearance.
+ */
+export interface GrabberOptions {
+  /**
+   * The width of the grabber pill.
+   *
+   * @default iOS: 36, Android: 32
+   */
+  width?: number;
+  /**
+   * The height of the grabber pill.
+   *
+   * @default iOS: 5, Android: 4
+   */
+  height?: number;
+  /**
+   * The top margin of the grabber from the sheet edge.
+   *
+   * @default iOS: 5, Android: 16
+   */
+  topMargin?: number;
+  /**
+   * The corner radius of the grabber pill.
+   *
+   * @default height / 2
+   */
+  cornerRadius?: number;
+  /**
+   * The color of the grabber.
+   * Uses native vibrancy/material styling when not provided.
+   */
+  color?: ColorValue;
+  /**
+   * Whether the grabber color adapts to light/dark mode.
+   * When enabled, the grabber uses vibrancy effect on iOS and
+   * adjusts color based on the current theme on Android.
+   *
+   * @default true
+   */
+  adaptive?: boolean;
+}
+
+/**
+ * Options for customizing (e.g. localizing) the accessibility strings
+ * announced by screen readers.
+ *
+ * On iOS, the grabber strings only apply when `grabberOptions` is provided.
+ * Without it, iOS uses the system grabber which is already localized.
+ */
+export interface AccessibilityOptions {
+  /**
+   * The accessibility label of the grabber.
+   *
+   * @default iOS: 'Sheet Grabber', Android: 'Drag handle'
+   */
+  grabberLabel?: string;
+  /**
+   * The accessibility hint of the grabber.
+   *
+   * @platform ios
+   * @default 'Double-tap to expand. Swipe up or down to resize the sheet'
+   */
+  grabberHint?: string;
+  /**
+   * The value announced when the sheet is at the last detent.
+   *
+   * @default 'Expanded'
+   */
+  expandedValue?: string;
+  /**
+   * The value announced when the sheet is at the first detent.
+   *
+   * @default 'Collapsed'
+   */
+  collapsedValue?: string;
+  /**
+   * The value announced when the sheet is at an intermediate detent.
+   * Supports `{index}` and `{count}` placeholders.
+   *
+   * @default 'Detent {index} of {count}'
+   */
+  detentValue?: string;
+  /**
+   * The label of the expand accessibility action.
+   *
+   * @platform android
+   * @default 'Expand'
+   */
+  expandActionLabel?: string;
+  /**
+   * The label of the collapse accessibility action.
+   *
+   * @platform android
+   * @default 'Collapse'
+   */
+  collapseActionLabel?: string;
+  /**
+   * The title announced when the sheet appears.
+   * Sets the accessibility pane title on Android and the
+   * hidden dialog title on Web.
+   *
+   * @platform android, web
+   * @default Android: 'Bottom sheet', Web: 'Sheet'
+   */
+  paneTitle?: string;
+}
+
+/**
+ * Scroll edge effect style for iOS 26+.
+ * Controls the blur/gradient overlay applied to scroll view edges.
+ *
+ * @platform ios 26+
+ */
+export type ScrollEdgeEffect = 'automatic' | 'hard' | 'soft' | 'hidden';
+
+/**
+ * Options for scrollable behavior.
+ */
+export interface ScrollableOptions {
+  /**
+   * Extra offset when scrolling to the focused input when keyboard appears.
+   *
+   * @default 0
+   */
+  keyboardScrollOffset?: number;
+
+  /**
+   * Whether scrolling the content expands the sheet to the next detent.
+   * When `false`, only the grabber can expand the sheet.
+   *
+   * @default true
+   */
+  scrollingExpandsSheet?: boolean;
+
+  /**
+   * The scroll edge effect applied to the top edge of the scroll view.
+   *
+   * @platform ios 26+
+   * @default 'hidden'
+   */
+  topScrollEdgeEffect?: ScrollEdgeEffect;
+
+  /**
+   * The scroll edge effect applied to the bottom edge of the scroll view.
+   *
+   * @platform ios 26+
+   * @default 'hidden'
+   */
+  bottomScrollEdgeEffect?: ScrollEdgeEffect;
+}
 
 /**
- * Internal event payload for size changes (not exposed to users)
- * @internal
+ * Options for header behavior
  */
-export interface SizeChangeEventPayload {
-  width: number;
-  height: number;
+export interface HeaderOptions {
+  /**
+   * How the header participates in the sheet layout.
+   *
+   * - `'relative'`: The header takes up space above the content, and its height
+   *   is included in the `auto` detent calculation.
+   * - `'absolute'`: The header floats over the content, pinned to the top edge,
+   *   and is excluded from the `auto` detent calculation.
+   *
+   * @default 'relative'
+   */
+  position?: 'relative' | 'absolute';
 }
 
 /**
- * Internal event type for size changes (not exposed to users)
- * @internal
+ * Options for footer behavior
  */
-export type SizeChangeEvent = NativeSyntheticEvent<SizeChangeEventPayload>;
+export interface FooterOptions {
+  /**
+   * How the footer participates in the sheet layout.
+   *
+   * - `'relative'`: The footer takes up space below the content, pinned to the
+   *   bottom edge. Its height is included in the `auto` detent calculation but
+   *   excluded from the `peek` detent (it's pushed off-screen at peek).
+   * - `'absolute'`: The footer floats over the content, pinned to the bottom
+   *   edge. Its height is excluded from the `auto` detent calculation but
+   *   included in the `peek` detent.
+   *
+   * @default 'relative'
+   */
+  position?: 'relative' | 'absolute';
+
+  /**
+   * Adjusts how far an `absolute` footer rises when the keyboard opens.
+   * Positive values raise it higher; negative values reduce the rise.
+   * Pass `-insets.bottom` to tuck the footer's safe-area padding behind the keyboard.
+   * A `relative` footer stays in the layout flow behind the keyboard, so this has no effect.
+   *
+   * @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.
+   *
+   * @default true
+   */
+  interaction?: boolean;
+}
+
+/**
+ * Inset adjustment behavior for the sheet content.
+ */
+export type InsetAdjustment =
+  /**
+   * Automatically adjusts the sheet height to account for system insets (safe area).
+   * This ensures the sheet content is properly inset from system UI elements.
+   */
+  | 'automatic'
+  /**
+   * Does not adjust the sheet height for system insets.
+   * The sheet height is calculated purely from the detent values.
+   */
+  | 'never';
 
 /**
  * Blur style mapped to native values in IOS.
  *
  * @platform ios
  */
-export type BlurTint =
+export type BackgroundBlur =
   | 'light'
   | 'dark'
   | 'default'
-  | 'extraLight'
+  | 'extra-light'
   | 'regular'
   | 'prominent'
-  | 'systemUltraThinMaterial'
-  | 'systemThinMaterial'
-  | 'systemMaterial'
-  | 'systemThickMaterial'
-  | 'systemChromeMaterial'
-  | 'systemUltraThinMaterialLight'
-  | 'systemThinMaterialLight'
-  | 'systemMaterialLight'
-  | 'systemThickMaterialLight'
-  | 'systemChromeMaterialLight'
-  | 'systemUltraThinMaterialDark'
-  | 'systemThinMaterialDark'
-  | 'systemMaterialDark'
-  | 'systemThickMaterialDark'
-  | 'systemChromeMaterialDark';
+  | 'system-ultra-thin-material'
+  | 'system-thin-material'
+  | 'system-material'
+  | 'system-thick-material'
+  | 'system-chrome-material'
+  | 'system-ultra-thin-material-light'
+  | 'system-thin-material-light'
+  | 'system-material-light'
+  | 'system-thick-material-light'
+  | 'system-chrome-material-light'
+  | 'system-ultra-thin-material-dark'
+  | 'system-thin-material-dark'
+  | 'system-material-dark'
+  | 'system-thick-material-dark'
+  | 'system-chrome-material-dark';
 
 /**
  * Supported Sheet detent.
- *
- * @platform android
- * @platform ios 15+
  */
 export type SheetDetent =
   /**
    * Auto resize based on content height, clamped to container height.
-   * Use the `maxHeight` prop to set a custom limit.
+   * Use the `maxContentHeight` prop to set a custom limit.
    *
    * @platform android
    * @platform ios 16+
    */
   | 'auto'
 
+  /**
+   * Collapsed height based on the combined `header` and `footer` heights.
+   * Render a `TrueSheetPeek` component within the content to also include
+   * the content up to its bottom edge.
+   * Falls back to a fixed height of `150` when none is provided.
+   *
+   * @platform android
+   * @platform ios 16+
+   */
+  | 'peek'
+
   /**
    * Relative height as a fraction (0-1) of the available height.
    * For example, 0.5 represents 50% of the available height.
@@ -126,6 +366,9 @@ export interface TrueSheetProps extends ViewProps {
    * detents={['auto', 0.6, 1]}
    * ```
    *
+   * @note It's recommended to sort detents from smallest to largest.
+   * When using `auto`, place it at the first index if you plan to adjust content dynamically.
+   *
    * @default [0.5, 1]
    */
   detents?: SheetDetent[];
@@ -134,8 +377,6 @@ export interface TrueSheetProps extends ViewProps {
    * Specify whether the sheet background is dimmed.
    * Set to `false` to allow interaction with the background components.
    *
-   * @platform android
-   * @platform ios 15+
    * @default true
    */
   dimmed?: boolean;
@@ -162,7 +403,7 @@ export interface TrueSheetProps extends ViewProps {
    *
    * @default 0
    */
-  dimmedIndex?: number;
+  dimmedDetentIndex?: number;
 
   /**
    * Prevents interactive dismissal of the Sheet.
@@ -172,9 +413,16 @@ export interface TrueSheetProps extends ViewProps {
   dismissible?: boolean;
 
   /**
-   * Main sheet background color.
+   * Enables or disables dragging the sheet to resize it.
+   * When disabled, the sheet becomes static and can only be resized programmatically.
+   *
+   * @default true
+   */
+  draggable?: boolean;
 
-   * @default white
+  /**
+   * Main sheet background color.
+   * Uses system default when not provided.
    */
   backgroundColor?: ColorValue;
 
@@ -184,49 +432,131 @@ export interface TrueSheetProps extends ViewProps {
    * - `undefined` (not provided): Uses system default corner radius
    * - `0`: Sharp corners (no rounding)
    * - `> 0`: Custom corner radius value
-   *
-   * @platform android
-   * @platform ios 15+
    */
   cornerRadius?: number;
 
   /**
-   * Shows native grabber (or handle) on IOS.
+   * Shows a native grabber (or drag handle) on the sheet.
+   *
+   * iOS uses the native `UISheetPresentationController` grabber.
+   * Android renders a native view following Material Design 3 specifications.
    *
-   * @platform ios
    * @default true
    */
   grabber?: boolean;
 
   /**
-   * Grabber props to be used for android grabber or handle.
+   * Options for customizing the grabber appearance.
+   * Only applies when `grabber` is `true`.
+   */
+  grabberOptions?: GrabberOptions;
+
+  /**
+   * Options for customizing (e.g. localizing) the accessibility strings
+   * announced by screen readers.
+   */
+  accessibilityOptions?: AccessibilityOptions;
+
+  /**
+   * Controls the sheet presentation style on iPad and web (landscape/tablet).
+   * - `'page'`: bottom-attached page sheet (full or readable width).
+   * - `'form'`: centered floating form sheet (default form-sheet width).
    *
-   * @platform android
+   * `'form'` is absolute — `maxContentWidth` is ignored when set.
+   *
+   * @platform ios 17+, web
+   * @default 'page'
    */
-  grabberProps?: TrueSheetGrabberProps;
+  presentation?: 'page' | 'form';
 
   /**
    * The blur effect style on iOS.
-   * Overrides `backgroundColor` if set.
+   * Blends with `backgroundColor` when provided.
    *
    * @platform ios
    */
-  blurTint?: BlurTint;
+  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.
    */
-  maxHeight?: number;
+  maxContentHeight?: number;
+
+  /**
+   * The maximum width of the sheet content.
+   * On Android and Web, defaults to `640dp`. On iOS, the sheet uses system default width.
+   *
+   * Ignored on phones in portrait orientation.
+   */
+  maxContentWidth?: number;
+
+  /**
+   * Anchors the sheet to the specified horizontal edge.
+   *
+   * - `'center'`: Centers the sheet horizontally (default).
+   * - `'left'`: Anchors the sheet to the left edge.
+   * - `'right'`: Anchors the sheet to the right edge.
+   *
+   * Ignored on phones in portrait orientation.
+   *
+   * @default 'center'
+   */
+  anchor?: 'left' | 'center' | 'right';
 
   /**
-   * Allows the sheet to extend behind the status bar when fully expanded in edge-to-edge mode.
-   * When false (default), the sheet stops at the bottom of the status bar.
+   * The offset from the screen edge.
+   * Only applies when `anchor` is `'left'` or `'right'`.
    *
    * @platform android
-   * @default false
+   * @platform web
+   * @default 16
    */
-  edgeToEdgeFullScreen?: boolean;
+  anchorOffset?: number;
+
+  /**
+   * Controls how the sheet adjusts its height for system insets (safe area).
+   *
+   * - `'automatic'`: Adds the bottom safe area inset to the sheet height,
+   *    ensuring content is properly inset from system UI elements.
+   * - `'never'`: Does not adjust for insets; height is calculated purely from detent values.
+   *
+   * @default 'automatic'
+   */
+  insetAdjustment?: InsetAdjustment;
+
+  /**
+   * The elevation (shadow depth) of the sheet.
+   *
+   * @platform android
+   * @platform web
+   * @default 4
+   */
+  elevation?: number;
+
+  /**
+   * A component that is fixed at the top of the Sheet content.
+   * Useful for search bars, titles, or other header content.
+   */
+  header?: ComponentType<unknown> | ReactElement;
+
+  /**
+   * Style for the header container.
+   */
+  headerStyle?: StyleProp<ViewStyle>;
+
+  /**
+   * Options for header behavior.
+   */
+  headerOptions?: HeaderOptions;
 
   /**
    * A component that floats at the bottom of the Sheet.
@@ -234,13 +564,35 @@ export interface TrueSheetProps extends ViewProps {
   footer?: ComponentType<unknown> | ReactElement;
 
   /**
-   * Determines how the software keyboard will impact the layout of the sheet.
-   * Set to `pan` if you're working with `FlatList` with a `TextInput`.
+   * Style for the footer container.
+   */
+  footerStyle?: StyleProp<ViewStyle>;
+
+  /**
+   * Options for scrollable behavior.
+   */
+  scrollableOptions?: ScrollableOptions;
+
+  /**
+   * Options for footer behavior.
+   */
+  footerOptions?: FooterOptions;
+
+  /**
+   * Renders the sheet as a detached floating card, not attached to the bottom edge.
    *
-   * @platform android
-   * @default resize
+   * @platform web
+   * @default false
+   */
+  detached?: boolean;
+
+  /**
+   * The offset from the bottom edge when [`detached`](#detached) is enabled.
+   *
+   * @platform web
+   * @default 16
    */
-  keyboardMode?: 'resize' | 'pan';
+  detachedOffset?: number;
 
   /**
    * Called when the sheet's content is mounted and ready.
@@ -278,27 +630,18 @@ export interface TrueSheetProps extends ViewProps {
   /**
    * Called when the sheet has began dragging.
    * Comes with the detent info.
-   *
-   * @platform android
-   * @platform ios 15+
    */
   onDragBegin?: (event: DragBeginEvent) => void;
 
   /**
    * Called when the sheet is being dragged.
    * Comes with the detent info.
-   *
-   * @platform android
-   * @platform ios 15+
    */
   onDragChange?: (event: DragChangeEvent) => void;
 
   /**
    * Called when the sheet dragging has ended.
    * Comes with the detent info.
-   *
-   * @platform android
-   * @platform ios 15+
    */
   onDragEnd?: (event: DragEndEvent) => void;
 
@@ -306,9 +649,120 @@ export interface TrueSheetProps extends ViewProps {
    * Called when the sheet's position changes.
    * This fires continuously during sheet position changes.
    * Comes with the detent info.
+   */
+  onPositionChange?: (event: PositionChangeEvent) => void;
+
+  /**
+   * Called when the sheet is about to regain focus because a sheet presented on top of it is being dismissed.
+   */
+  onWillFocus?: (event: WillFocusEvent) => void;
+
+  /**
+   * Called when the sheet regains focus after a sheet presented on top of it is dismissed.
+   */
+  onDidFocus?: (event: DidFocusEvent) => void;
+
+  /**
+   * Called when the sheet is about to lose focus because another sheet is being presented on top of it.
+   */
+  onWillBlur?: (event: WillBlurEvent) => void;
+
+  /**
+   * Called when the sheet loses focus because another sheet is presented on top of it.
+   */
+  onDidBlur?: (event: DidBlurEvent) => void;
+
+  /**
+   * Called when the hardware back button is pressed on Android.
+   * Optionally return `false` to let the back event propagate to other handlers (e.g. navigation).
    *
    * @platform android
-   * @platform ios 15+
    */
-  onPositionChange?: (event: PositionChangeEvent) => void;
+  onBackPress?: () => boolean | void;
+}
+
+/**
+ * Imperative methods available on a TrueSheet ref.
+ *
+ * Example:
+ * ```tsx
+ * const sheetRef = useRef<TrueSheetMethods>(null);
+ * sheetRef.current?.present();
+ * ```
+ */
+export interface TrueSheetMethods {
+  /**
+   * Present the sheet at a given detent index.
+   *
+   * @param index - The detent index to present at (default: `0`).
+   * @param animated - Whether to animate the presentation (default: `true`). Ignored on web.
+   */
+  present(index?: number, animated?: boolean): Promise<void>;
+
+  /**
+   * Resize the sheet to a given detent index.
+   *
+   * @param index - The detent index to resize to.
+   */
+  resize(index: number): Promise<void>;
+
+  /**
+   * Dismiss this sheet and all sheets presented on top of it in a single animation.
+   *
+   * @param animated - Whether to animate the dismissal (default: `true`). Ignored on web.
+   */
+  dismiss(animated?: boolean): Promise<void>;
+
+  /**
+   * Dismiss only the sheets presented on top of this sheet, keeping this sheet presented.
+   * No-op if no sheets are presented on top.
+   *
+   * @param animated - Whether to animate the dismissal (default: `true`). Ignored on web.
+   */
+  dismissStack(animated?: boolean): Promise<void>;
+}
+
+/**
+ * Static methods exposed on the `TrueSheet` component for controlling sheets by `name`.
+ *
+ * Example:
+ * ```ts
+ * TrueSheet.present('my-sheet')
+ * ```
+ *
+ * @note Not supported on web — use the `useTrueSheet()` hook instead.
+ */
+export interface TrueSheetStaticMethods {
+  /**
+   * Present the sheet with the given `name`.
+   *
+   * @throws if no sheet with the given `name` is registered.
+   */
+  present(name: string, index?: number, animated?: boolean): Promise<void>;
+
+  /**
+   * Resize the sheet with the given `name`.
+   *
+   * @throws if no sheet with the given `name` is registered.
+   */
+  resize(name: string, index: number): Promise<void>;
+
+  /**
+   * Dismiss the sheet with the given `name` and all sheets presented on top of it.
+   *
+   * @throws if no sheet with the given `name` is registered.
+   */
+  dismiss(name: string, animated?: boolean): Promise<void>;
+
+  /**
+   * Dismiss only the sheets presented on top of the sheet with the given `name`.
+   *
+   * @throws if no sheet with the given `name` is registered.
+   */
+  dismissStack(name: string, animated?: boolean): Promise<void>;
+
+  /**
+   * Dismiss every presented sheet, from the top of the stack downward.
+   */
+  dismissAll(animated?: boolean): Promise<void>;
 }