@lodev09/react-native-true-sheet 4.0.0-beta.3 → 4.0.0-beta.30

package/src/TrueSheetBackground.tsx

@@ -0,0 +1,17 @@
+import { StyleSheet, View } from 'react-native';
+import type { TrueSheetProps } from './TrueSheet.types';
+
+export const TrueSheetBackground = ({
+  background,
+  backgroundStyle,
+}: Pick<TrueSheetProps, 'background' | 'backgroundStyle'>) => (
+  <View
+    pointerEvents="none"
+    style={[
+      StyleSheet.absoluteFill,
+      { backgroundColor: StyleSheet.flatten(backgroundStyle)?.backgroundColor },
+    ]}
+  >
+    {background}
+  </View>
+);

package/src/TrueSheetOverlay.tsx

@@ -0,0 +1,24 @@
+import { StyleSheet, type ViewProps } from 'react-native';
+
+import TrueSheetOverlayViewNativeComponent from './fabric/TrueSheetOverlayViewNativeComponent';
+
+/**
+ * Renders its children in a native layer above every presented sheet — for
+ * toasts, dialogs, and other content a sheet must not cover.
+ * Fills the window; touches that miss its children pass through to the views beneath.
+ */
+export const TrueSheetOverlay = ({ style, ...rest }: ViewProps) => (
+  <TrueSheetOverlayViewNativeComponent {...rest} style={[styles.overlay, style]} />
+);
+
+const styles = StyleSheet.create({
+  // Sized to the window from native — absolute so it takes no layout space.
+  // Children render in a native container, so the host itself must never
+  // catch touches (Android forces it visible on layout).
+  overlay: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    pointerEvents: 'none',
+  },
+});

package/src/TrueSheetOverlay.web.tsx

@@ -0,0 +1,33 @@
+/// <reference lib="dom" />
+import { useLayoutEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { StyleSheet, View, type ViewProps } from 'react-native';
+
+/**
+ * Renders its children in a layer above every presented sheet — for
+ * toasts, dialogs, and other content a sheet must not cover.
+ * Fills the window; touches that miss its children pass through to the views beneath.
+ */
+export const TrueSheetOverlay = ({ style, ...rest }: ViewProps) => {
+  // Portal target appended to the body so it stacks above the sheets' portal
+  const [container] = useState(() =>
+    typeof document !== 'undefined' ? document.createElement('div') : null
+  );
+
+  useLayoutEffect(() => {
+    if (!container) return;
+
+    container.style.cssText = 'position:fixed;inset:0;pointer-events:none';
+    document.body.appendChild(container);
+    return () => {
+      container.remove();
+    };
+  }, [container]);
+
+  if (!container) return null;
+
+  return createPortal(
+    <View pointerEvents="box-none" {...rest} style={[StyleSheet.absoluteFill, style]} />,
+    container
+  );
+};

package/src/TrueSheetPeek.web.tsx

@@ -1,16 +1,15 @@
-import { createContext, type RefObject, useContext, useEffect, useRef } from 'react';
+import { createContext, type RefObject, useContext, useLayoutEffect, useRef } from 'react';
 import { type LayoutChangeEvent, View, type ViewProps } from 'react-native';
 
-import { getDOMElement } from './web/dom';
-
 /**
- * Reports the measured peek content height to the owning TrueSheet.
+ * Registers a peek with the owning TrueSheet so it can measure the peek live.
  * @internal
  */
 export interface TrueSheetPeekContextValue {
   contentRef: RefObject<View | null>;
-  peekRef: RefObject<View | null>;
-  setPeekContentHeight: (height: number) => void;
+  attachPeek: (view: View) => void;
+  detachPeek: (view: View) => void;
+  measurePeek: (view: View) => void;
 }
 
 export const TrueSheetPeekContext = createContext<TrueSheetPeekContextValue | null>(null);
@@ -19,14 +18,19 @@ export const TrueSheetPeekContext = createContext<TrueSheetPeekContextValue | nu
  * Distance from the top of the content view to the bottom of the peek view,
  * so the peek view's offset within the content (padding, views above it)
  * counts toward the peek detent. Both rects live in the drawer's transformed
- * subtree, so an in-flight translate cancels out of the delta.
+ * subtree, so an in-flight translate cancels out of the delta. Rounded so the
+ * sub-pixel noise of a mid-transition measurement doesn't register as a
+ * change — the content re-measures every frame while the snap animates, and
+ * a new value would restart the snap.
  * @internal
  */
 export const measurePeekContentHeight = (
   peekElement: HTMLElement,
   contentElement: HTMLElement
 ): number =>
-  peekElement.getBoundingClientRect().bottom - contentElement.getBoundingClientRect().top;
+  Math.round(
+    peekElement.getBoundingClientRect().bottom - contentElement.getBoundingClientRect().top
+  );
 
 /**
  * Wrapper component that marks its children as the sheet's peek content.
@@ -36,25 +40,23 @@ export const measurePeekContentHeight = (
  */
 export const TrueSheetPeek = ({ onLayout, ...rest }: ViewProps) => {
   const context = useContext(TrueSheetPeekContext);
-  const localRef = useRef<View>(null);
+  const viewRef = useRef<View>(null);
 
-  // Register into the sheet's peek ref so it can measure the peek live
-  // during detent geometry computation (state lags the first willPresent).
-  const viewRef = context?.peekRef ?? localRef;
+  // Attach by instance rather than sharing a ref — during a screen swap the
+  // incoming peek mounts before the outgoing one unmounts, and a shared ref
+  // would be nulled by the outgoing unmount.
+  useLayoutEffect(() => {
+    const view = viewRef.current;
+    if (!context || !view) return;
 
-  useEffect(() => () => context?.setPeekContentHeight(0), [context]);
+    context.attachPeek(view);
+    return () => context.detachPeek(view);
+  }, [context]);
 
   const handleLayout = (event: LayoutChangeEvent) => {
-    if (context) {
-      const peekElement = getDOMElement(viewRef.current);
-      const contentElement = getDOMElement(context.contentRef.current);
-
-      const bottom =
-        peekElement && contentElement
-          ? measurePeekContentHeight(peekElement, contentElement)
-          : event.nativeEvent.layout.height;
-
-      context.setPeekContentHeight(bottom);
+    const view = viewRef.current;
+    if (context && view) {
+      context.measurePeek(view);
     }
 
     onLayout?.(event);

package/src/TrueSheetProvider.web.tsx

@@ -13,7 +13,13 @@ import {
 
 import type { TrueSheetMethods, TrueSheetStaticMethods } from './TrueSheet.types';
 
-type SheetRef = RefObject<TrueSheetMethods | null>;
+export interface SheetHandle {
+  methods: TrueSheetMethods;
+  // dismiss() without the already-dismissed warning, for stack-wide dismissals
+  dismissQuietly: (animated?: boolean) => Promise<void>;
+}
+
+type SheetRef = RefObject<SheetHandle | null>;
 type NodeRef = RefObject<HTMLDivElement | null>;
 
 interface StackEntry {
@@ -23,7 +29,8 @@ interface StackEntry {
 }
 
 interface SheetContextValue {
-  registerByName: (name: string, ref: SheetRef) => () => void;
+  registerSheet: (ref: SheetRef, name?: string) => () => void;
+  getSheets: () => ReadonlySet<SheetRef>;
   resolveByName: (name: string) => TrueSheetMethods;
   pushOpen: (entry: StackEntry) => void;
   popOpen: (entry: StackEntry) => void;
@@ -44,6 +51,7 @@ export interface TrueSheetProviderProps {
 }
 
 export function TrueSheetProvider({ children }: TrueSheetProviderProps) {
+  const sheetsRef = useRef<Set<SheetRef>>(new Set());
   const namedSheetsRef = useRef<Map<string, SheetRef>>(new Map());
   const stackRef = useRef<readonly StackEntry[]>(EMPTY_STACK);
   const listenersRef = useRef<Set<() => void>>(new Set());
@@ -72,17 +80,20 @@ export function TrueSheetProvider({ children }: TrueSheetProviderProps) {
     const notify = () => listenersRef.current.forEach((listener) => listener());
 
     return {
-      registerByName: (name, ref) => {
-        namedSheetsRef.current.set(name, ref);
+      registerSheet: (ref, name) => {
+        sheetsRef.current.add(ref);
+        if (name) namedSheetsRef.current.set(name, ref);
         return () => {
-          if (namedSheetsRef.current.get(name) === ref) {
+          sheetsRef.current.delete(ref);
+          if (name && namedSheetsRef.current.get(name) === ref) {
             namedSheetsRef.current.delete(name);
           }
         };
       },
+      getSheets: () => sheetsRef.current,
       resolveByName: (name) => {
         const ref = namedSheetsRef.current.get(name);
-        const methods = ref?.current;
+        const methods = ref?.current?.methods;
         if (!methods) {
           throw new Error(`TrueSheet: no sheet registered with name "${name}"`);
         }
@@ -145,11 +156,9 @@ export function useTrueSheet(): TrueSheetStaticMethods {
       resize: (name, index) => ctx.resolveByName(name).resize(index),
       dismiss: (name, animated) => ctx.resolveByName(name).dismiss(animated),
       dismissStack: (name, animated) => ctx.resolveByName(name).dismissStack(animated),
+      // Every sheet, not just the open stack — it misses a present() that hasn't committed yet
       dismissAll: async (animated) => {
-        const stack = ctx.getStackSnapshot();
-        await Promise.all(
-          [...stack].reverse().map((entry) => entry.ref.current?.dismiss(animated))
-        );
+        await Promise.all([...ctx.getSheets()].map((ref) => ref.current?.dismissQuietly(animated)));
       },
     };
   }, [ctx]);
@@ -158,8 +167,8 @@ export function useTrueSheet(): TrueSheetStaticMethods {
 export function useRegisterSheet(name: string | undefined, ref: SheetRef): void {
   const ctx = useContext(SheetContext);
   useEffect(() => {
-    if (!ctx || !name) return;
-    return ctx.registerByName(name, ref);
+    if (!ctx) return;
+    return ctx.registerSheet(ref, name);
   }, [ctx, name, ref]);
 }
 
@@ -211,7 +220,7 @@ export function useSheetStack(
       const idx = snapshot.findIndex((e) => e.ref === ref);
       if (idx < 0) return;
       const above = snapshot.slice(idx + 1);
-      await Promise.all([...above].reverse().map((e) => e.ref.current?.dismiss(animated)));
+      await Promise.all([...above].reverse().map((e) => e.ref.current?.dismissQuietly(animated)));
     },
     [ctx, ref]
   );

package/src/detentBackgrounds.ts

@@ -0,0 +1,24 @@
+import type { DetentBackground } from './TrueSheet.types';
+
+export function normalizeDetentBackground(entry: DetentBackground | null | undefined) {
+  return typeof entry === 'string' ? { color: entry } : entry;
+}
+
+export function getDetentBackgroundIndex(
+  height: number,
+  detentHeights: readonly number[],
+  displayedIndex: number
+): number {
+  if (detentHeights.length === 0) return -1;
+
+  let nextIndex = Math.max(0, Math.min(displayedIndex, detentHeights.length - 1));
+  let distance = Math.abs(height - detentHeights[nextIndex]!);
+  for (let index = 0; index < detentHeights.length; index++) {
+    const nextDistance = Math.abs(height - detentHeights[index]!);
+    if (nextDistance < distance) {
+      nextIndex = index;
+      distance = nextDistance;
+    }
+  }
+  return nextIndex;
+}

package/src/fabric/TrueSheetContentViewNativeComponent.ts

@@ -6,7 +6,7 @@ export interface NativeProps extends ViewProps {
 }
 
 // interfaceOnly: shadow node/state/descriptor are custom (common/cpp) so the
-// content can be bounded to the container when a ScrollView is pinned
+// content can be bounded to the container when a ScrollView is detected
 export default codegenNativeComponent<NativeProps>('TrueSheetContentView', {
   interfaceOnly: true,
 });

package/src/fabric/TrueSheetFooterViewNativeComponent.ts

@@ -1,12 +1,11 @@
-import type { ViewProps } from 'react-native';
-import type { WithDefault } from 'react-native/Libraries/Types/CodegenTypes';
+import type { CodegenTypes, ViewProps } from 'react-native';
 import { codegenNativeComponent } from 'react-native';
 
 export interface NativeProps extends ViewProps {
   // Seeds the footer's first layout with the sheet's bottom safe-area inset
   // (insetAdjustment: 'automatic') so a late-set footer doesn't need a second
   // layout pass — and a visible sheet resize — once native pushes the inset
-  autoBottomInset?: WithDefault<boolean, false>;
+  autoBottomInset?: CodegenTypes.WithDefault<boolean, false>;
 }
 
 // interfaceOnly: shadow node/state/descriptor are custom (common/cpp) so the

package/src/fabric/TrueSheetOverlayViewNativeComponent.ts

@@ -0,0 +1,12 @@
+import type { ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+
+export interface NativeProps extends ViewProps {
+  // No props needed - sized to the window from native
+}
+
+// interfaceOnly: shadow node/state/descriptor are custom (common/cpp) so the
+// overlay is sized to the window
+export default codegenNativeComponent<NativeProps>('TrueSheetOverlayView', {
+  interfaceOnly: true,
+});

package/src/fabric/TrueSheetViewNativeComponent.ts

@@ -1,87 +1,98 @@
-import type { ColorValue, ProcessedColorValue, ViewProps } from 'react-native';
-import type {
-  DirectEventHandler,
-  Double,
-  Int32,
-  WithDefault,
-} from 'react-native/Libraries/Types/CodegenTypes';
+import type { CodegenTypes, ColorValue, ProcessedColorValue, ViewProps } from 'react-native';
 import { codegenNativeComponent } from 'react-native';
 
 type GrabberOptionsType = Readonly<{
-  width?: Double;
-  height?: Double;
-  topMargin?: Double;
-  cornerRadius?: WithDefault<Double, -1>;
+  width?: CodegenTypes.Double;
+  height?: CodegenTypes.Double;
+  topMargin?: CodegenTypes.Double;
+  cornerRadius?: CodegenTypes.WithDefault<CodegenTypes.Double, -1>;
   color?: ProcessedColorValue | null;
-  adaptive?: WithDefault<boolean, true>;
+  adaptive?: CodegenTypes.WithDefault<boolean, true>;
 }>;
 
 type AccessibilityOptionsType = Readonly<{
-  grabberLabel?: WithDefault<string, 'Sheet Grabber'>;
-  grabberHint?: WithDefault<string, 'Double-tap to expand. Swipe up or down to resize the sheet'>;
-  expandedValue?: WithDefault<string, 'Expanded'>;
-  collapsedValue?: WithDefault<string, 'Collapsed'>;
-  detentValue?: WithDefault<string, 'Detent {index} of {count}'>;
-  expandActionLabel?: WithDefault<string, 'Expand'>;
-  collapseActionLabel?: WithDefault<string, 'Collapse'>;
-  paneTitle?: WithDefault<string, 'Bottom sheet'>;
-}>;
-
-type BlurOptionsType = Readonly<{
-  intensity?: WithDefault<Double, -1>;
-  interaction?: WithDefault<boolean, true>;
+  grabberLabel?: CodegenTypes.WithDefault<string, 'Sheet Grabber'>;
+  grabberHint?: CodegenTypes.WithDefault<
+    string,
+    'Double-tap to expand. Swipe up or down to resize the sheet'
+  >;
+  expandedValue?: CodegenTypes.WithDefault<string, 'Expanded'>;
+  collapsedValue?: CodegenTypes.WithDefault<string, 'Collapsed'>;
+  detentValue?: CodegenTypes.WithDefault<string, 'Detent {index} of {count}'>;
+  expandActionLabel?: CodegenTypes.WithDefault<string, 'Expand'>;
+  collapseActionLabel?: CodegenTypes.WithDefault<string, 'Collapse'>;
+  paneTitle?: CodegenTypes.WithDefault<string, 'Bottom sheet'>;
 }>;
 
 type ScrollEdgeEffect = 'automatic' | 'hard' | 'soft' | 'hidden';
 
 type ScrollableOptionsType = Readonly<{
-  keyboardScrollOffset?: WithDefault<Double, 0>;
-  scrollingExpandsSheet?: WithDefault<boolean, true>;
-  topScrollEdgeEffect?: WithDefault<ScrollEdgeEffect, 'hidden'>;
-  bottomScrollEdgeEffect?: WithDefault<ScrollEdgeEffect, 'hidden'>;
+  contentInsetAdjustment?: CodegenTypes.WithDefault<
+    'automatic' | 'safe-area' | 'footer' | 'never',
+    'automatic'
+  >;
+  keyboardScrollOffset?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  keyboardOffset?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  scrollingExpandsSheet?: CodegenTypes.WithDefault<boolean, true>;
+  topScrollEdgeEffect?: CodegenTypes.WithDefault<ScrollEdgeEffect, 'hidden'>;
+  bottomScrollEdgeEffect?: CodegenTypes.WithDefault<ScrollEdgeEffect, 'hidden'>;
 }>;
 
 type FooterOptionsType = Readonly<{
   // Named uniquely across option structs — codegen derives the enum name from
   // the field name, so a second `position` would redefine TrueSheetViewPosition
-  footerPosition?: WithDefault<'relative' | 'absolute', 'relative'>;
-  keyboardOffset?: WithDefault<Double, 0>;
+  footerPosition?: CodegenTypes.WithDefault<'relative' | 'absolute', 'relative'>;
+  keyboardOffset?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  avoidKeyboard?: CodegenTypes.WithDefault<boolean, true>;
 }>;
 
 type HeaderOptionsType = Readonly<{
-  position?: WithDefault<'relative' | 'absolute', 'relative'>;
+  position?: CodegenTypes.WithDefault<'relative' | 'absolute', 'relative'>;
+}>;
+
+type FoldOptionsType = Readonly<{
+  hingeDetentIndex?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
+  hingeBehavior?: CodegenTypes.WithDefault<'none' | 'avoid' | 'snap', 'none'>;
 }>;
 
 export interface DetentInfoEventPayload {
-  index: Int32;
-  position: Double;
-  detent: Double;
+  index: CodegenTypes.Int32;
+  position: CodegenTypes.Double;
+  detent: CodegenTypes.Double;
 }
 
 export interface PositionChangeEventPayload {
-  index: Double;
-  position: Double;
-  detent: Double;
+  index: CodegenTypes.Double;
+  position: CodegenTypes.Double;
+  detent: CodegenTypes.Double;
   realtime: boolean;
 }
 
 export interface NativeProps extends ViewProps {
   // Array properties
-  detents?: ReadonlyArray<Double>;
+  detents?: ReadonlyArray<CodegenTypes.Double>;
+  detentBackgrounds?: ReadonlyArray<
+    Readonly<{
+      color?: ProcessedColorValue | null;
+      blur?: string;
+    }>
+  >;
 
   // Number properties - use 0 as default to avoid nil insertion
-  maxContentHeight?: WithDefault<Double, 0>;
-  maxContentWidth?: WithDefault<Double, 0>;
-  cornerRadius?: WithDefault<Double, -1>;
-  elevation?: WithDefault<Double, -1>;
+  maxContentHeight?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  maxContentWidth?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  cornerRadius?: CodegenTypes.WithDefault<CodegenTypes.Double, -1>;
+  elevation?: CodegenTypes.WithDefault<CodegenTypes.Double, -1>;
 
   // Color properties
   backgroundColor?: ColorValue;
-  initialDetentIndex?: WithDefault<Int32, -1>;
-  dimmedDetentIndex?: WithDefault<Int32, 0>;
+  initialDetentIndex?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
+  dimColor?: ColorValue;
+  dimOpacity?: CodegenTypes.WithDefault<CodegenTypes.Double, -1>;
+  dimmedDetentIndex?: CodegenTypes.WithDefault<CodegenTypes.Int32, 0>;
 
   // String properties - use empty string as default to avoid nil insertion
-  backgroundBlur?: WithDefault<
+  backgroundBlur?: CodegenTypes.WithDefault<
     | 'none'
     | 'light'
     | 'dark'
@@ -107,42 +118,47 @@ export interface NativeProps extends ViewProps {
     'none'
   >;
 
-  anchor?: WithDefault<'left' | 'center' | 'right', 'center'>;
-  anchorOffset?: WithDefault<Double, 16>;
-  insetAdjustment?: WithDefault<'automatic' | 'never', 'automatic'>;
-
-  // Blur options
-  blurOptions?: BlurOptionsType;
+  placement?: CodegenTypes.WithDefault<
+    'automatic' | 'leading' | 'center' | 'trailing',
+    'automatic'
+  >;
+  placementOffset?: CodegenTypes.WithDefault<CodegenTypes.Double, 16>;
+  insetAdjustment?: CodegenTypes.WithDefault<'automatic' | 'never', 'automatic'>;
+  dismissThreshold?: CodegenTypes.WithDefault<'half' | 'short', 'half'>;
 
   // Boolean properties - match defaults from TrueSheet.types.ts
-  grabber?: WithDefault<boolean, true>;
+  grabber?: CodegenTypes.WithDefault<boolean, true>;
   grabberOptions?: GrabberOptionsType;
   accessibilityOptions?: AccessibilityOptionsType;
-  dismissible?: WithDefault<boolean, true>;
-  draggable?: WithDefault<boolean, true>;
-  dimmed?: WithDefault<boolean, true>;
-  initialDetentAnimated?: WithDefault<boolean, true>;
+  dismissible?: CodegenTypes.WithDefault<boolean, true>;
+  draggable?: CodegenTypes.WithDefault<boolean, true>;
+  dimmed?: CodegenTypes.WithDefault<boolean, true>;
+  initialDetentAnimated?: CodegenTypes.WithDefault<boolean, true>;
+  // React tag of the scrollable component within the content (see scrollableRef)
+  scrollableHandle?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
   scrollableOptions?: ScrollableOptionsType;
   headerOptions?: HeaderOptionsType;
   footerOptions?: FooterOptionsType;
-  presentation?: WithDefault<'page' | 'form', 'page'>;
+  foldOptions?: FoldOptionsType;
+  presentation?: CodegenTypes.WithDefault<'page' | 'form', 'page'>;
 
   // Event handlers
-  onMount?: DirectEventHandler<null>;
-  onWillPresent?: DirectEventHandler<DetentInfoEventPayload>;
-  onDidPresent?: DirectEventHandler<DetentInfoEventPayload>;
-  onWillDismiss?: DirectEventHandler<null>;
-  onDidDismiss?: DirectEventHandler<null>;
-  onDetentChange?: DirectEventHandler<DetentInfoEventPayload>;
-  onDragBegin?: DirectEventHandler<DetentInfoEventPayload>;
-  onDragChange?: DirectEventHandler<DetentInfoEventPayload>;
-  onDragEnd?: DirectEventHandler<DetentInfoEventPayload>;
-  onPositionChange?: DirectEventHandler<PositionChangeEventPayload>;
-  onWillFocus?: DirectEventHandler<null>;
-  onDidFocus?: DirectEventHandler<null>;
-  onWillBlur?: DirectEventHandler<null>;
-  onDidBlur?: DirectEventHandler<null>;
-  onVisibilityChange?: DirectEventHandler<Readonly<{ visible: boolean }>>;
+  onMount?: CodegenTypes.DirectEventHandler<null>;
+  onWillPresent?: CodegenTypes.DirectEventHandler<DetentInfoEventPayload>;
+  onDidPresent?: CodegenTypes.DirectEventHandler<DetentInfoEventPayload>;
+  onWillDismiss?: CodegenTypes.DirectEventHandler<null>;
+  onDidDismiss?: CodegenTypes.DirectEventHandler<null>;
+  onDismissAttempt?: CodegenTypes.DirectEventHandler<null>;
+  onDetentChange?: CodegenTypes.DirectEventHandler<DetentInfoEventPayload>;
+  onDragBegin?: CodegenTypes.DirectEventHandler<DetentInfoEventPayload>;
+  onDragChange?: CodegenTypes.DirectEventHandler<DetentInfoEventPayload>;
+  onDragEnd?: CodegenTypes.DirectEventHandler<DetentInfoEventPayload>;
+  onPositionChange?: CodegenTypes.DirectEventHandler<PositionChangeEventPayload>;
+  onWillFocus?: CodegenTypes.DirectEventHandler<null>;
+  onDidFocus?: CodegenTypes.DirectEventHandler<null>;
+  onWillBlur?: CodegenTypes.DirectEventHandler<null>;
+  onDidBlur?: CodegenTypes.DirectEventHandler<null>;
+  onVisibilityChange?: CodegenTypes.DirectEventHandler<Readonly<{ visible: boolean }>>;
 }
 
 export default codegenNativeComponent<NativeProps>('TrueSheetView', {

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './TrueSheet';
 export * from './TrueSheet.types';
 export { TrueSheetPeek } from './TrueSheetPeek';
+export { TrueSheetOverlay } from './TrueSheetOverlay';
 export { TrueSheetProvider, useTrueSheet } from './TrueSheetProvider';

package/src/mocks/index.ts

@@ -2,6 +2,7 @@ import React, { createElement, isValidElement, type ReactNode } from 'react';
 import { View, type ViewProps } from 'react-native';
 
 import type { TrueSheetProps, TrueSheetStaticMethods } from '../TrueSheet.types';
+import { TrueSheetBackground } from '../TrueSheetBackground';
 
 interface TrueSheetState {
   shouldRenderNativeView: boolean;
@@ -54,8 +55,15 @@ export class TrueSheet extends React.Component<TrueSheetProps, TrueSheetState> {
   }
 
   render() {
-    const { children, style } = this.props;
-    return React.createElement(View, { style }, this.renderHeader(), children, this.renderFooter());
+    const { children, style, background, backgroundStyle } = this.props;
+    return React.createElement(
+      View,
+      { style },
+      React.createElement(TrueSheetBackground, { background, backgroundStyle }),
+      this.renderHeader(),
+      children,
+      this.renderFooter()
+    );
   }
 }
 
@@ -66,6 +74,13 @@ export function TrueSheetPeek({ children, ...rest }: ViewProps) {
   return React.createElement(View, rest, children);
 }
 
+/**
+ * Mock TrueSheetOverlay component for testing.
+ */
+export function TrueSheetOverlay({ children, ...rest }: ViewProps) {
+  return React.createElement(View, rest, children);
+}
+
 /**
  * Mock TrueSheetProvider for testing.
  */

package/src/mocks/navigationExpoRouter.ts

@@ -1,6 +1,5 @@
-import type { ParamListBase } from '@react-navigation/native';
-
-import type { TrueSheetNavigationProp } from '../navigation/types';
+import type { ParamListBase } from '../navigation/expo-router/base-types';
+import type { TrueSheetNavigationProp } from '../navigation/expo-router/types';
 import {
   TrueSheetActions,
   useTrueSheetNavigation as useTrueSheetNavigationMock,
@@ -22,8 +21,10 @@ export const Sheet = Object.assign(
  * Mock useTrueSheetNavigation hook for testing.
  */
 export const useTrueSheetNavigation = jest.fn(
+  // Double cast: the shared mock is typed against React Navigation, this entry
+  // against Expo Router's vendored copy — identical shapes, unrelated declarations
   <T extends ParamListBase = ParamListBase>(): TrueSheetNavigationProp<T> =>
-    useTrueSheetNavigationMock() as TrueSheetNavigationProp<T>
+    useTrueSheetNavigationMock() as unknown as TrueSheetNavigationProp<T>
 );
 
 export { TrueSheetActions };
@@ -37,4 +38,4 @@ export type {
   TrueSheetNavigationProp,
   TrueSheetNavigationState,
   TrueSheetScreenProps,
-} from '../navigation/types';
+} from '../navigation/expo-router/types';

package/src/navigation/base-types.ts

@@ -0,0 +1,20 @@
+/**
+ * Base navigation types for the React Navigation entry point.
+ *
+ * The Expo Router entry has its own copy sourced from `expo-router/react-navigation`
+ * (see `./expo-router/base-types`) because Expo Router apps never install
+ * `@react-navigation/*` — importing it there would silently resolve to `any`.
+ */
+export type {
+  DefaultNavigatorOptions,
+  Descriptor,
+  NavigationAction,
+  NavigationHelpers,
+  NavigationProp,
+  NavigationState,
+  ParamListBase,
+  RouteProp,
+  Router,
+  StackActionHelpers,
+  StackRouterOptions,
+} from '@react-navigation/core';