@oneplatformdev/react-native-uikit 1.2.9 → 1.2.11

package/README.md

@@ -359,7 +359,11 @@ For non-scrolling keyboard avoidance, omitting `keyboardAvoidingBehavior` keeps
 
 `CustomAlert` animates a centered modal with a dismissible backdrop. Supply `header`, children, and optional `footer` content; compose your own actions with `Button`. Optional `closeAction` accepts an icon and an application-supplied accessibility label. No strings are translated by the kit.
 
-`BottomModal` provides the reference-style slide/drag dismissal and keyboard-height-aware positioning. Supply `children`, `onClose`, and optionally `title`, `customHeader`, and a labeled `closeAction` icon. `Keyboard.dismiss()` and the close animation start together; `closeRef` can trigger the same close path externally. The kit does not render app-specific toasts.
+`BottomModal` provides slide/handle-drag dismissal and keyboard-height-aware positioning. Supply `children`, `visible`, `onClose`, and optionally `title`, `customHeader`, and a labeled `closeAction` icon. Without `sizing`, the existing `isFullScreen` prop still selects the original fullscreen layout; otherwise the modal follows its content. When both are supplied, `sizing` takes precedence over `isFullScreen`. Use `sizing={{ mode: 'content' }}` for intrinsic height, `sizing={{ mode: 'fixed', fraction: 0.5 }}` for half the available height, `sizing={{ mode: 'fullscreen' }}` to fill the area below `topInset`, or `sizing={{ mode: 'expandable', initialFraction: 0.6 }}` for two positions: 60% and the full available height. A fixed fraction must be finite, greater than 0 and at most 1; invalid values throw in development. In production, positive finite values above 1 clamp to 1, while non-positive or non-finite values use a fixed 0.5 fallback. An expandable fraction must be finite, greater than 0 and less than 1; invalid values throw in development and use 0.6 in production. Normal `ScrollView` or `FlatList` children remain caller-owned for tall content.
+
+`topInset` defaults to the resolved top safe-area inset; `topInset={0}` starts at the physical top. `showHeader={false}` removes the package header and ignores `customHeader`. Expandable sizing requires `showHeader=true` to provide a resize gesture target; disabling it throws in development and leaves the modal collapsed without gesture resizing in production. A `customHeader` participates in the same handle gesture area. `backdrop={false}` hides the backdrop; an object may override its `color`, `opacity`, or `dismissOnPress`, leaving other defaults intact. `cornerRadius` is an unscaled design value. `dragToDismiss="handle"` is the default; `"none"` disables drag dismissal. In expandable mode, dragging the header up expands; dragging down collapses first, then dismisses from collapsed only when drag dismissal is enabled. The height animates after gesture release rather than tracking the finger. With `"none"`, header resizing still works. Scrollable content owns its gestures and does not resize the modal. Each new presentation starts collapsed; orientation changes recompute both heights. Backdrop and hardware Back always request close rather than collapse.
+
+A close action, dismissible backdrop, handle gesture, or Android hardware back calls `onCloseRequest(reason)` once when closing starts. The keyboard is dismissed, and the existing `onClose` runs after the 250-ms exit animation; the parent still owns `visible`. An external `visible: true → false` hides immediately, cancels any pending package animation, and does not call `onCloseRequest` or `onClose`. `onDismiss` fires once after a committed controlled `true → false` transition, not after a guaranteed native OS dialog teardown. An internal close calls it only if the parent subsequently sets `visible=false`; do not use it yet to sequence native modal stacking or camera/gallery presentation. `closeRef` retains its previous close behavior without a close-request reason. The kit does not render app-specific toasts.
 
 Both modes require consumers to install the declared native peers used by these components: `@d11/react-native-fast-image`, `react-native-keyboard-controller`, `react-native-linear-gradient`, `react-native-reanimated`, and `react-native-safe-area-context`. Applications using keyboard-aware or safe-area behavior should configure the providers and native setup required by those libraries. The kit does not bundle those peers or install them through `add`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneplatformdev/react-native-uikit",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "bin": {

package/src/components/BottomModal/index.ts

@@ -1,2 +1,8 @@
 export { BottomModal } from './ui/BottomModal';
-export type { BottomModalCloseAction, BottomModalProps } from './types/types';
+export type {
+    BottomModalBackdrop,
+    BottomModalCloseAction,
+    BottomModalCloseReason,
+    BottomModalProps,
+    BottomModalSizing,
+} from './types/types';

package/src/components/BottomModal/presenters/useBottomModal.ts

@@ -1,9 +1,12 @@
-import { useCallback, useEffect, useMemo } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { Animated, Easing, Keyboard, PanResponder, useWindowDimensions } from 'react-native';
-import type { BottomModalProps } from '../types/types';
+import type { BottomModalCloseReason, BottomModalProps } from '../types/types';
 import { useBottomModalInsets } from './useBottomModalInsets';
 
-type UseBottomModalProps = Pick<BottomModalProps, 'onClose' | 'closeRef'>;
+type UseBottomModalProps = Pick<
+    BottomModalProps,
+    'visible' | 'onClose' | 'onCloseRequest' | 'onDismiss' | 'closeRef' | 'topInset' | 'sizing' | 'dragToDismiss'
+>;
 
 const CLOSE_DISTANCE = 120;
 const CLOSE_VELOCITY = 1;
@@ -12,18 +15,75 @@ const CLOSE_ANIMATION_DURATION = 250;
 
 const isDragDownGesture = (gestureState: { dx: number; dy: number }) =>
     gestureState.dy > 0 && Math.abs(gestureState.dy) > Math.abs(gestureState.dx);
+const isVerticalGesture = (gestureState: { dx: number; dy: number }) =>
+    gestureState.dy !== 0 && Math.abs(gestureState.dy) > Math.abs(gestureState.dx);
 
 export const useBottomModal = ({
+    visible,
     onClose,
+    onCloseRequest,
+    onDismiss,
     closeRef,
+    topInset: requestedTopInset,
+    sizing,
+    dragToDismiss,
 }: UseBottomModalProps) => {
     const { height } = useWindowDimensions();
-    const { topInset, bottomInset } = useBottomModalInsets();
-    const translateY = useMemo(() => new Animated.Value(height), [height]);
-    const backdropOpacity = useMemo(() => new Animated.Value(0), []);
+    const { topInset, bottomInset } = useBottomModalInsets(requestedTopInset);
+    const isExpandable = sizing?.mode === 'expandable';
+    const initialFraction = sizing?.mode === 'expandable' ? sizing.initialFraction : undefined;
+    const validInitialFraction = initialFraction !== undefined && Number.isFinite(initialFraction)
+        && initialFraction > 0 && initialFraction < 1;
+    if (__DEV__ && isExpandable && !validInitialFraction) {
+        throw new Error('BottomModal expandable initialFraction must be finite, greater than 0 and less than 1.');
+    }
+    const maxHeight = Math.max(0, height - topInset);
+    const collapsedHeight = maxHeight * (validInitialFraction ? initialFraction : 0.6);
+    const [translateY] = useState(() => new Animated.Value(height));
+    const [backdropOpacity] = useState(() => new Animated.Value(0));
+    const [expandableHeight] = useState(() => new Animated.Value(collapsedHeight));
+    const expandedRef = useRef(false);
+    const previousVisibleRef = useRef(visible);
+    const visibleRef = useRef(visible);
+    const openedRef = useRef(false);
+    const closingRef = useRef(false);
+    const animationIdRef = useRef(0);
+    const onCloseRef = useRef(onClose);
+    const onCloseRequestRef = useRef(onCloseRequest);
+    visibleRef.current = visible;
+    onCloseRef.current = onClose;
+    onCloseRequestRef.current = onCloseRequest;
+
+    useLayoutEffect(() => {
+        if (!isExpandable) {
+            expandedRef.current = false;
+            expandableHeight.stopAnimation();
+            return;
+        }
+        expandableHeight.stopAnimation();
+        expandableHeight.setValue(expandedRef.current ? maxHeight : collapsedHeight);
+    }, [collapsedHeight, expandableHeight, isExpandable, maxHeight]);
+
+    const onResize = useCallback((expanded: boolean) => {
+        if (closingRef.current) return;
+        expandedRef.current = expanded;
+        expandableHeight.stopAnimation();
+        Animated.timing(expandableHeight, {
+            toValue: expanded ? maxHeight : collapsedHeight,
+            duration: CLOSE_ANIMATION_DURATION,
+            easing: Easing.out(Easing.cubic),
+            useNativeDriver: false,
+        }).start();
+    }, [collapsedHeight, expandableHeight, maxHeight]);
 
     const onRunCloseAnimation = useCallback(
-        (shouldNotify = true) => {
+        (shouldNotify: boolean, reason?: BottomModalCloseReason) => {
+            if (closingRef.current) return;
+            closingRef.current = true;
+            const animationId = ++animationIdRef.current;
+            if (reason) onCloseRequestRef.current?.(reason);
+            Keyboard.dismiss();
+            if (isExpandable) expandableHeight.stopAnimation();
             translateY.stopAnimation();
             backdropOpacity.stopAnimation();
             Animated.parallel([
@@ -40,24 +100,22 @@ export const useBottomModal = ({
                     useNativeDriver: true,
                 }),
             ]).start(({ finished }) => {
-                if (finished && shouldNotify) onClose();
+                if (!finished || animationId !== animationIdRef.current) return;
+                closingRef.current = false;
+                if (shouldNotify) onCloseRef.current();
             });
         },
-        [backdropOpacity, height, onClose, translateY],
+        [backdropOpacity, expandableHeight, height, isExpandable, translateY],
     );
-    const onCloseAnimated = useCallback(
-        (shouldNotify = true) => {
-            Keyboard.dismiss();
-            onRunCloseAnimation(shouldNotify);
-        },
-        [onRunCloseAnimation],
-    );
-    const onClosePress = useCallback(() => onCloseAnimated(), [onCloseAnimated]);
-    const onShow = useCallback(() => {
+    const onRunOpenAnimation = useCallback((reset: boolean) => {
+        ++animationIdRef.current;
+        closingRef.current = false;
         translateY.stopAnimation();
         backdropOpacity.stopAnimation();
-        translateY.setValue(height);
-        backdropOpacity.setValue(0);
+        if (reset) {
+            translateY.setValue(height);
+            backdropOpacity.setValue(0);
+        }
         Animated.parallel([
             Animated.timing(translateY, {
                 toValue: 0,
@@ -73,6 +131,51 @@ export const useBottomModal = ({
             }),
         ]).start();
     }, [backdropOpacity, height, translateY]);
+    const onShow = useCallback(() => {
+        if (!visibleRef.current || closingRef.current || openedRef.current) return;
+        openedRef.current = true;
+        onRunOpenAnimation(true);
+    }, [onRunOpenAnimation]);
+
+    useLayoutEffect(() => {
+        const wasVisible = previousVisibleRef.current;
+        previousVisibleRef.current = visible;
+        if (visible === wasVisible) return;
+        ++animationIdRef.current;
+        closingRef.current = false;
+        translateY.stopAnimation();
+        backdropOpacity.stopAnimation();
+        if (visible) {
+            expandedRef.current = false;
+            if (isExpandable) expandableHeight.setValue(collapsedHeight);
+            openedRef.current = true;
+            onRunOpenAnimation(false);
+        } else {
+            openedRef.current = false;
+            if (isExpandable) {
+                expandableHeight.stopAnimation();
+                expandedRef.current = false;
+                expandableHeight.setValue(collapsedHeight);
+            }
+            translateY.setValue(height);
+            backdropOpacity.setValue(0);
+            // Report the controlled hidden commit, not native dialog teardown.
+            onDismiss?.();
+        }
+    }, [backdropOpacity, collapsedHeight, expandableHeight, height, isExpandable, onDismiss, onRunOpenAnimation, translateY, visible]);
+
+    const onClosePress = useCallback(() => onRunCloseAnimation(true), [onRunCloseAnimation]);
+    const onCloseAction = useCallback(() => onRunCloseAnimation(true, 'closeAction'), [onRunCloseAnimation]);
+    const onBackdropPress = useCallback(() => onRunCloseAnimation(true, 'backdrop'), [onRunCloseAnimation]);
+    const onHardwareBack = useCallback(() => onRunCloseAnimation(true, 'hardwareBack'), [onRunCloseAnimation]);
+    const onGestureClose = useCallback(() => onRunCloseAnimation(true, 'gesture'), [onRunCloseAnimation]);
+
+    useEffect(() => () => {
+        ++animationIdRef.current;
+        translateY.stopAnimation();
+        backdropOpacity.stopAnimation();
+        expandableHeight.stopAnimation();
+    }, [backdropOpacity, expandableHeight, translateY]);
 
     useEffect(() => {
         if (!closeRef) return;
@@ -82,23 +185,35 @@ export const useBottomModal = ({
 
     const panResponder = useMemo(
         () => PanResponder.create({
-            onMoveShouldSetPanResponderCapture: (_, gestureState) => isDragDownGesture(gestureState),
-            onMoveShouldSetPanResponder: (_, gestureState) => isDragDownGesture(gestureState),
+            onMoveShouldSetPanResponderCapture: (_, gestureState) => isExpandable
+                ? isVerticalGesture(gestureState) : isDragDownGesture(gestureState),
+            onMoveShouldSetPanResponder: (_, gestureState) => isExpandable
+                ? isVerticalGesture(gestureState) : isDragDownGesture(gestureState),
             onPanResponderMove: (_, gestureState) => {
+                if (isExpandable) return;
                 if (gestureState.dy > 0) translateY.setValue(gestureState.dy);
             },
             onPanResponderRelease: (_, gestureState) => {
+                if (isExpandable) {
+                    const swipedUp = -gestureState.dy > CLOSE_DISTANCE || -gestureState.vy > CLOSE_VELOCITY;
+                    const swipedDown = gestureState.dy > CLOSE_DISTANCE || gestureState.vy > CLOSE_VELOCITY;
+                    if (expandedRef.current && swipedDown) onResize(false);
+                    else if (!expandedRef.current && swipedUp) onResize(true);
+                    else if (!expandedRef.current && swipedDown && dragToDismiss === 'handle') onGestureClose();
+                    return;
+                }
                 if (gestureState.dy > CLOSE_DISTANCE || gestureState.vy > CLOSE_VELOCITY) {
-                    onCloseAnimated();
+                    onGestureClose();
                     return;
                 }
                 Animated.spring(translateY, { toValue: 0, useNativeDriver: true, bounciness: 0, speed: 18 }).start();
             },
             onPanResponderTerminate: () => {
+                if (isExpandable) return;
                 Animated.spring(translateY, { toValue: 0, useNativeDriver: true, bounciness: 0, speed: 18 }).start();
             },
         }),
-        [onCloseAnimated, translateY],
+        [dragToDismiss, isExpandable, onGestureClose, onResize, translateY],
     );
 
     return {
@@ -107,7 +222,11 @@ export const useBottomModal = ({
         bottomInset,
         translateY,
         backdropOpacity,
-        onClosePress,
+        expandableHeight,
+        isExpandable,
+        onCloseAction,
+        onBackdropPress,
+        onHardwareBack,
         onShow,
         panHandlers: panResponder.panHandlers,
     };

package/src/components/BottomModal/presenters/useBottomModalInsets.ts

@@ -7,9 +7,13 @@ const getAndroidNavigationInset = () => {
     return Math.max(0, Dimensions.get('screen').height - Dimensions.get('window').height);
 };
 
-export const useBottomModalInsets = () => {
+export const useBottomModalInsets = (requestedTopInset?: number) => {
     const { top, bottom } = useSafeAreaInsets();
-    const topInset = useMemo(() => Math.max(top, initialWindowMetrics?.insets.top || 0), [top]);
+    const topInset = useMemo(() => {
+        const defaultTopInset = Math.max(top, initialWindowMetrics?.insets.top || 0);
+        return requestedTopInset === undefined || !Number.isFinite(requestedTopInset)
+            ? defaultTopInset : Math.max(0, requestedTopInset);
+    }, [requestedTopInset, top]);
     const bottomInset = useMemo(
         () => Math.max(bottom, initialWindowMetrics?.insets.bottom || 0, getAndroidNavigationInset()),
         [bottom],

package/src/components/BottomModal/types/types.ts

@@ -8,6 +8,20 @@ export interface BottomModalCloseAction {
     accessibilityHint?: string;
 }
 
+export type BottomModalSizing =
+    | { mode: 'content' }
+    | { mode: 'fixed'; fraction: number }
+    | { mode: 'fullscreen' }
+    | { mode: 'expandable'; initialFraction: number };
+
+export type BottomModalBackdrop = false | {
+    color?: string;
+    opacity?: number;
+    dismissOnPress?: boolean;
+};
+
+export type BottomModalCloseReason = 'closeAction' | 'backdrop' | 'gesture' | 'hardwareBack';
+
 export interface BottomModalProps {
     visible: boolean;
     onClose: () => void;
@@ -20,4 +34,12 @@ export interface BottomModalProps {
     contentContainerStyle?: StyleProp<ViewStyle>;
     isFullScreen?: boolean;
     shouldAvoidKeyboard?: boolean;
+    sizing?: BottomModalSizing;
+    topInset?: number;
+    showHeader?: boolean;
+    backdrop?: BottomModalBackdrop;
+    cornerRadius?: number;
+    dragToDismiss?: 'none' | 'handle';
+    onCloseRequest?: (reason: BottomModalCloseReason) => void;
+    onDismiss?: () => void;
 }

package/src/components/BottomModal/ui/BottomModal.tsx

@@ -20,54 +20,82 @@ export const BottomModal = ({
     contentContainerStyle,
     isFullScreen = false,
     shouldAvoidKeyboard = true,
+    sizing,
+    topInset,
+    showHeader = true,
+    backdrop,
+    cornerRadius,
+    dragToDismiss = 'handle',
+    onCloseRequest,
+    onDismiss,
 }: BottomModalProps) => {
     const { colors, spacing, radius } = useUITheme();
     const scaling = useScaling();
+    const backdropOptions = backdrop === false ? undefined : backdrop;
+    const backdropColor = backdropOptions?.color ?? colors.text;
+    const targetBackdropOpacity = backdropOptions?.opacity !== undefined && Number.isFinite(backdropOptions.opacity)
+        ? Math.min(1, Math.max(0, backdropOptions.opacity)) : 0.5;
+    const dismissOnBackdropPress = backdropOptions?.dismissOnPress ?? true;
+    const resolvedCornerRadius = cornerRadius !== undefined && Number.isFinite(cornerRadius)
+        ? Math.max(0, cornerRadius) : undefined;
     const {
         bottomInset,
         height,
-        topInset,
+        topInset: resolvedTopInset,
         translateY,
         backdropOpacity,
-        onClosePress,
+        expandableHeight,
+        isExpandable,
+        onCloseAction,
+        onBackdropPress,
+        onHardwareBack,
         onShow,
         panHandlers,
-    } = useBottomModal({ onClose, closeRef });
+    } = useBottomModal({ visible, onClose, onCloseRequest, onDismiss, closeRef, topInset, sizing, dragToDismiss });
 
     const {
         modalContentStyle,
         animatedBackdropStyle,
         animatedKeyboardContainerStyle,
         animatedKeyboardBackgroundStyle,
+        isBoundedHeight,
     } = useBottomModalAnimatedStyles(
-        height, topInset, bottomInset, translateY, backdropOpacity, isFullScreen, shouldAvoidKeyboard,
+        height, resolvedTopInset, bottomInset, translateY, backdropOpacity,
+        isFullScreen, shouldAvoidKeyboard, sizing, targetBackdropOpacity, expandableHeight,
     );
 
+    if (__DEV__ && isExpandable && !showHeader) {
+        throw new Error('BottomModal expandable sizing requires showHeader=true for its resize gesture.');
+    }
+
     const styles = useMemo(
-        () => getStyles(colors, spacing, radius, scaling, bottomInset),
-        [bottomInset, colors, radius, scaling, spacing],
+        () => getStyles(colors, spacing, radius, scaling, bottomInset, backdropColor, resolvedCornerRadius),
+        [backdropColor, bottomInset, colors, radius, resolvedCornerRadius, scaling, spacing],
     );
 
     return (
-        <Modal visible={visible} transparent animationType="none" statusBarTranslucent onRequestClose={onClosePress} onShow={onShow}>
+        <Modal visible={visible} transparent animationType="none" statusBarTranslucent
+            onRequestClose={onHardwareBack} onShow={onShow}>
             <View style={styles.modalContainer}>
-                <Animated.View pointerEvents="none" style={[styles.backdrop, animatedBackdropStyle]} />
+                {backdrop !== false ? (
+                    <>
+                        <Animated.View pointerEvents="none" style={[styles.backdrop, animatedBackdropStyle]} />
+                        {dismissOnBackdropPress ? (
+                            <Pressable accessible={false} importantForAccessibility="no"
+                                onPress={onBackdropPress} style={StyleSheet.absoluteFill} />
+                        ) : null}
+                    </>
+                ) : null}
                 <Reanimated.View pointerEvents="none" style={[styles.keyboardBackground, animatedKeyboardBackgroundStyle]} />
-                <Pressable
-                    accessible={false}
-                    importantForAccessibility="no"
-                    onPress={onClosePress}
-                    style={StyleSheet.absoluteFill}
-                />
 
                 <Reanimated.View style={animatedKeyboardContainerStyle}>
                     <Animated.View
                         accessibilityViewIsModal
-                        onAccessibilityEscape={onClosePress}
+                        onAccessibilityEscape={onCloseAction}
                         style={[styles.modalContent, modalContentStyle]}
                     >
-                        <View style={[styles.container, isFullScreen && styles.fullScreenContainer]}>
-                            <View {...panHandlers}>
+                        <View style={[styles.container, isBoundedHeight && styles.fullScreenContainer]}>
+                            {showHeader ? <View {...(isExpandable || dragToDismiss === 'handle' ? panHandlers : {})}>
                                 <TouchableWithoutFeedback>
                                     {customHeader ? (
                                         <View>{customHeader}</View>
@@ -84,7 +112,7 @@ export const BottomModal = ({
                                                     accessibilityRole="button"
                                                     accessibilityLabel={closeAction.accessibilityLabel}
                                                     accessibilityHint={closeAction.accessibilityHint ?? title}
-                                                    onPress={onClosePress}
+                                                    onPress={onCloseAction}
                                                     style={styles.closeButton}
                                                 >
                                                     {closeAction.icon}
@@ -93,10 +121,10 @@ export const BottomModal = ({
                                         </View>
                                     )}
                                 </TouchableWithoutFeedback>
-                            </View>
+                            </View> : null}
                             <View style={[
                                 styles.contentContainer,
-                                isFullScreen && styles.fullScreenContentContainer,
+                                isBoundedHeight && styles.boundedContentContainer,
                                 contentContainerStyle,
                             ]}>
                                 {children}

package/src/components/BottomModal/ui/styles.ts

@@ -1,10 +1,10 @@
 import { useMemo } from 'react';
 import { Animated, StyleSheet } from 'react-native';
-import type { ViewStyle } from 'react-native';
 import { useAnimatedStyle } from 'react-native-reanimated';
 import { useAnimatedKeyboard } from 'react-native-keyboard-controller';
 import type { UIColors, UIRadius, UISpacing } from '../../../theme';
 import type { ScalingFunctions } from '../../../utils';
+import type { BottomModalSizing } from '../types/types';
 
 export const getStyles = (
     colors: UIColors,
@@ -12,6 +12,8 @@ export const getStyles = (
     radius: UIRadius,
     scaling: ScalingFunctions,
     bottomInset: number,
+    backdropColor: string,
+    cornerRadius?: number,
 ) => {
     const styles = StyleSheet.create({
         modalContainer: {
@@ -24,7 +26,7 @@ export const getStyles = (
             right: 0,
             bottom: 0,
             left: 0,
-            backgroundColor: colors.text,
+            backgroundColor: backdropColor,
         },
         keyboardBackground: {
             position: 'absolute',
@@ -35,8 +37,8 @@ export const getStyles = (
         },
         modalContent: {
             backgroundColor: colors.background,
-            borderTopLeftRadius: scaling.scaleHorizontal(radius.lg),
-            borderTopRightRadius: scaling.scaleHorizontal(radius.lg),
+            borderTopLeftRadius: scaling.scaleHorizontal(cornerRadius ?? radius.lg),
+            borderTopRightRadius: scaling.scaleHorizontal(cornerRadius ?? radius.lg),
             overflow: 'hidden',
             flexShrink: 1,
         },
@@ -78,7 +80,7 @@ export const getStyles = (
             paddingBottom: bottomInset + scaling.scaleVertical(spacing.lg),
             flexShrink: 1,
         },
-        fullScreenContentContainer: {
+        boundedContentContainer: {
             flex: 1,
             minHeight: 0,
         },
@@ -95,12 +97,26 @@ export const useBottomModalAnimatedStyles = (
     backdropOpacity: Animated.Value,
     isFullScreen: boolean,
     shouldAvoidKeyboard: boolean,
+    sizing?: BottomModalSizing,
+    targetBackdropOpacity = 0.5,
+    expandableHeight?: Animated.Value,
 ) => {
-    const maxHeight = height - topInset;
+    const maxHeight = Math.max(0, height - topInset);
+    const mode = sizing?.mode ?? (isFullScreen ? 'fullscreen' : 'content');
+    const fraction = sizing?.mode === 'fixed' ? sizing.fraction : undefined;
+    const validFraction = fraction !== undefined && Number.isFinite(fraction) && fraction > 0 && fraction <= 1;
+    if (__DEV__ && sizing?.mode === 'fixed' && !validFraction) {
+        throw new Error('BottomModal fixed fraction must be finite and greater than 0 and at most 1.');
+    }
+    const resolvedFraction = fraction !== undefined && Number.isFinite(fraction) && fraction > 0
+        ? Math.min(1, fraction) : 0.5;
+    const modalHeight = mode === 'fullscreen' ? maxHeight
+        : mode === 'fixed' ? maxHeight * resolvedFraction : undefined;
+    const isBoundedHeight = modalHeight !== undefined || mode === 'expandable';
     const { height: keyboardHeight } = useAnimatedKeyboard();
     const animatedBackdropStyle = useMemo(
-        () => ({ opacity: backdropOpacity.interpolate({ inputRange: [0, 1], outputRange: [0, 0.5] }) }),
-        [backdropOpacity],
+        () => ({ opacity: backdropOpacity.interpolate({ inputRange: [0, 1], outputRange: [0, targetBackdropOpacity] }) }),
+        [backdropOpacity, targetBackdropOpacity],
     );
     const animatedKeyboardContainerStyle = useAnimatedStyle(() => {
         if (!shouldAvoidKeyboard) return { marginBottom: 0, maxHeight };
@@ -110,10 +126,14 @@ export const useBottomModalAnimatedStyles = (
     const animatedKeyboardBackgroundStyle = useAnimatedStyle(() => ({
         height: shouldAvoidKeyboard ? Math.max(keyboardHeight.value - bottomInset, 0) : 0,
     }));
-    const modalContentStyle = useMemo<ViewStyle>(
-        () => ({ maxHeight, height: isFullScreen ? maxHeight : undefined, transform: [{ translateY }] }),
-        [isFullScreen, maxHeight, translateY],
+    const modalContentStyle = useMemo(
+        () => ({
+            maxHeight,
+            height: mode === 'expandable' ? expandableHeight : modalHeight,
+            transform: [{ translateY }],
+        }),
+        [expandableHeight, maxHeight, modalHeight, mode, translateY],
     );
 
-    return { animatedBackdropStyle, animatedKeyboardContainerStyle, animatedKeyboardBackgroundStyle, modalContentStyle };
+    return { animatedBackdropStyle, animatedKeyboardContainerStyle, animatedKeyboardBackgroundStyle, modalContentStyle, isBoundedHeight };
 };