@ankhorage/surface 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @ankhorage/surface
 
+## 4.1.0
+
+### Minor Changes
+
+- 6476bf4: Add the provider-backed BottomSheetModal controller with `BottomSheetProvider` and
+  `useBottomSheet()` through the dedicated `@ankhorage/surface/bottom-sheet` entrypoint.
+
 ## 4.0.0
 
 ### Major Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/surface
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v3.4.6](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v4.0.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Cross-platform UI foundation for React Native and React Native Web. Provides theming, layout primitives, and core building blocks for modern apps.
 

package/dist/features/bottom-sheet/BottomSheetContext.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import type { BottomSheetController } from '../../types/bottomSheet';
+export declare const BottomSheetContext: React.Context<BottomSheetController | null>;
+//# sourceMappingURL=BottomSheetContext.d.ts.map

package/dist/features/bottom-sheet/BottomSheetContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheetContext.d.ts","sourceRoot":"","sources":["../../../src/features/bottom-sheet/BottomSheetContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE,eAAO,MAAM,kBAAkB,6CAA0D,CAAC"}

package/dist/features/bottom-sheet/BottomSheetContext.js

@@ -0,0 +1,3 @@
+import React from 'react';
+export const BottomSheetContext = React.createContext(null);
+//# sourceMappingURL=BottomSheetContext.js.map

package/dist/features/bottom-sheet/BottomSheetContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheetContext.js","sourceRoot":"","sources":["../../../src/features/bottom-sheet/BottomSheetContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC,aAAa,CAA+B,IAAI,CAAC,CAAC","sourcesContent":["import React from 'react';\n\nimport type { BottomSheetController } from '../../types/bottomSheet';\n\nexport const BottomSheetContext = React.createContext<BottomSheetController | null>(null);\n"]}

package/dist/features/bottom-sheet/BottomSheetProvider.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+/*** Installs the shared bottom-sheet modal host and controller for descendant consumers. */
+export declare function BottomSheetProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+//# sourceMappingURL=BottomSheetProvider.d.ts.map

package/dist/features/bottom-sheet/BottomSheetProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheetProvider.d.ts","sourceRoot":"","sources":["../../../src/features/bottom-sheet/BottomSheetProvider.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,qBAiD9E"}

package/dist/features/bottom-sheet/BottomSheetProvider.js

@@ -0,0 +1,61 @@
+import { BottomSheetBackdrop, BottomSheetModal, BottomSheetModalProvider, BottomSheetView, } from '@gorhom/bottom-sheet';
+import React from 'react';
+import { BottomSheetContext } from './BottomSheetContext';
+/*** Installs the shared bottom-sheet modal host and controller for descendant consumers. */
+export function BottomSheetProvider({ children }) {
+    const modalRef = React.useRef(null);
+    const activeRequestRef = React.useRef(null);
+    const presentedRef = React.useRef(false);
+    const [activeRequest, setActiveRequest] = React.useState(null);
+    const present = React.useCallback((options) => {
+        activeRequestRef.current = options;
+        setActiveRequest(options);
+    }, []);
+    const dismiss = React.useCallback(() => {
+        if (presentedRef.current) {
+            modalRef.current?.dismiss();
+            return;
+        }
+        const request = activeRequestRef.current;
+        activeRequestRef.current = null;
+        setActiveRequest(null);
+        request?.onDismiss?.();
+    }, []);
+    const handleDismiss = React.useCallback(() => {
+        const request = activeRequestRef.current;
+        presentedRef.current = false;
+        activeRequestRef.current = null;
+        setActiveRequest(null);
+        request?.onDismiss?.();
+    }, []);
+    const controller = React.useMemo(() => ({ dismiss, present }), [dismiss, present]);
+    return (<BottomSheetContext.Provider value={controller}>
+      <BottomSheetModalProvider>
+        {children}
+        <BottomSheetHost activeRequest={activeRequest} handleDismiss={handleDismiss} modalRef={modalRef} presentedRef={presentedRef}/>
+      </BottomSheetModalProvider>
+    </BottomSheetContext.Provider>);
+}
+/*** Renders and presents the single Gorhom modal owned by the provider. */
+function BottomSheetHost({ activeRequest, handleDismiss, modalRef, presentedRef, }) {
+    React.useEffect(() => {
+        if (!activeRequest || presentedRef.current) {
+            return;
+        }
+        presentedRef.current = true;
+        modalRef.current?.present();
+    }, [activeRequest, modalRef, presentedRef]);
+    const renderBackdrop = useBottomSheetBackdrop(activeRequest?.dismissOnBackdropPress);
+    const snapPoints = React.useMemo(() => (activeRequest?.snapPoints ? [...activeRequest.snapPoints] : undefined), [activeRequest?.snapPoints]);
+    if (!activeRequest) {
+        return null;
+    }
+    return (<BottomSheetModal ref={modalRef} backdropComponent={renderBackdrop} enableDynamicSizing={activeRequest.enableDynamicSizing ?? true} enablePanDownToClose={activeRequest.enablePanDownToClose ?? true} index={activeRequest.initialIndex ?? 0} keyboardBehavior={activeRequest.keyboardBehavior ?? 'interactive'} keyboardBlurBehavior={activeRequest.keyboardBlurBehavior ?? 'restore'} onChange={activeRequest.onIndexChange} onDismiss={handleDismiss} snapPoints={snapPoints}>
+      <BottomSheetView>{activeRequest.content}</BottomSheetView>
+    </BottomSheetModal>);
+}
+/*** Creates the backdrop renderer for the active bottom-sheet request. */
+function useBottomSheetBackdrop(dismissOnBackdropPress) {
+    return React.useCallback((props) => (<BottomSheetBackdrop {...props} appearsOnIndex={0} disappearsOnIndex={-1} pressBehavior={dismissOnBackdropPress === false ? 'none' : 'close'}/>), [dismissOnBackdropPress]);
+}
+//# sourceMappingURL=BottomSheetProvider.js.map

package/dist/features/bottom-sheet/BottomSheetProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheetProvider.js","sourceRoot":"","sources":["../../../src/features/bottom-sheet/BottomSheetProvider.tsx"],"names":[],"mappings":"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","sourcesContent":["import {\n  BottomSheetBackdrop,\n  type BottomSheetBackdropProps,\n  BottomSheetModal,\n  BottomSheetModalProvider,\n  BottomSheetView,\n} from '@gorhom/bottom-sheet';\nimport React from 'react';\n\nimport type { BottomSheetController, BottomSheetPresentOptions } from '../../types/bottomSheet';\nimport { BottomSheetContext } from './BottomSheetContext';\n\n/*** Installs the shared bottom-sheet modal host and controller for descendant consumers. */\nexport function BottomSheetProvider({ children }: { children: React.ReactNode }) {\n  const modalRef = React.useRef<BottomSheetModal>(null);\n  const activeRequestRef = React.useRef<BottomSheetPresentOptions | null>(null);\n  const presentedRef = React.useRef(false);\n  const [activeRequest, setActiveRequest] = React.useState<BottomSheetPresentOptions | null>(null);\n\n  const present = React.useCallback((options: BottomSheetPresentOptions) => {\n    activeRequestRef.current = options;\n    setActiveRequest(options);\n  }, []);\n\n  const dismiss = React.useCallback(() => {\n    if (presentedRef.current) {\n      modalRef.current?.dismiss();\n      return;\n    }\n\n    const request = activeRequestRef.current;\n    activeRequestRef.current = null;\n    setActiveRequest(null);\n    request?.onDismiss?.();\n  }, []);\n\n  const handleDismiss = React.useCallback(() => {\n    const request = activeRequestRef.current;\n    presentedRef.current = false;\n    activeRequestRef.current = null;\n    setActiveRequest(null);\n    request?.onDismiss?.();\n  }, []);\n\n  const controller = React.useMemo<BottomSheetController>(\n    () => ({ dismiss, present }),\n    [dismiss, present],\n  );\n\n  return (\n    <BottomSheetContext.Provider value={controller}>\n      <BottomSheetModalProvider>\n        {children}\n        <BottomSheetHost\n          activeRequest={activeRequest}\n          handleDismiss={handleDismiss}\n          modalRef={modalRef}\n          presentedRef={presentedRef}\n        />\n      </BottomSheetModalProvider>\n    </BottomSheetContext.Provider>\n  );\n}\n\ninterface BottomSheetHostProps {\n  readonly activeRequest: BottomSheetPresentOptions | null;\n  readonly handleDismiss: () => void;\n  readonly modalRef: React.RefObject<BottomSheetModal | null>;\n  readonly presentedRef: React.RefObject<boolean>;\n}\n\n/*** Renders and presents the single Gorhom modal owned by the provider. */\nfunction BottomSheetHost({\n  activeRequest,\n  handleDismiss,\n  modalRef,\n  presentedRef,\n}: BottomSheetHostProps) {\n  React.useEffect(() => {\n    if (!activeRequest || presentedRef.current) {\n      return;\n    }\n\n    presentedRef.current = true;\n    modalRef.current?.present();\n  }, [activeRequest, modalRef, presentedRef]);\n\n  const renderBackdrop = useBottomSheetBackdrop(activeRequest?.dismissOnBackdropPress);\n  const snapPoints = React.useMemo(\n    () => (activeRequest?.snapPoints ? [...activeRequest.snapPoints] : undefined),\n    [activeRequest?.snapPoints],\n  );\n\n  if (!activeRequest) {\n    return null;\n  }\n\n  return (\n    <BottomSheetModal\n      ref={modalRef}\n      backdropComponent={renderBackdrop}\n      enableDynamicSizing={activeRequest.enableDynamicSizing ?? true}\n      enablePanDownToClose={activeRequest.enablePanDownToClose ?? true}\n      index={activeRequest.initialIndex ?? 0}\n      keyboardBehavior={activeRequest.keyboardBehavior ?? 'interactive'}\n      keyboardBlurBehavior={activeRequest.keyboardBlurBehavior ?? 'restore'}\n      onChange={activeRequest.onIndexChange}\n      onDismiss={handleDismiss}\n      snapPoints={snapPoints}\n    >\n      <BottomSheetView>{activeRequest.content}</BottomSheetView>\n    </BottomSheetModal>\n  );\n}\n\n/*** Creates the backdrop renderer for the active bottom-sheet request. */\nfunction useBottomSheetBackdrop(dismissOnBackdropPress: boolean | undefined) {\n  return React.useCallback(\n    (props: BottomSheetBackdropProps) => (\n      <BottomSheetBackdrop\n        {...props}\n        appearsOnIndex={0}\n        disappearsOnIndex={-1}\n        pressBehavior={dismissOnBackdropPress === false ? 'none' : 'close'}\n      />\n    ),\n    [dismissOnBackdropPress],\n  );\n}\n"]}

package/dist/features/bottom-sheet/public.d.ts

@@ -0,0 +1,4 @@
+export type { BottomSheetController, BottomSheetPresentOptions } from '../../types/bottomSheet';
+export { BottomSheetProvider } from './BottomSheetProvider';
+export { useBottomSheet } from './useBottomSheet';
+//# sourceMappingURL=public.d.ts.map

package/dist/features/bottom-sheet/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../../src/features/bottom-sheet/public.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/features/bottom-sheet/public.js

@@ -0,0 +1,3 @@
+export { BottomSheetProvider } from './BottomSheetProvider';
+export { useBottomSheet } from './useBottomSheet';
+//# sourceMappingURL=public.js.map

package/dist/features/bottom-sheet/public.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.js","sourceRoot":"","sources":["../../../src/features/bottom-sheet/public.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["export type { BottomSheetController, BottomSheetPresentOptions } from '../../types/bottomSheet';\nexport { BottomSheetProvider } from './BottomSheetProvider';\nexport { useBottomSheet } from './useBottomSheet';\n"]}

package/dist/features/bottom-sheet/useBottomSheet.d.ts

@@ -0,0 +1,4 @@
+import type { BottomSheetController } from '../../types/bottomSheet';
+/*** Returns the shared bottom-sheet controller installed by BottomSheetProvider. */
+export declare function useBottomSheet(): BottomSheetController;
+//# sourceMappingURL=useBottomSheet.d.ts.map

package/dist/features/bottom-sheet/useBottomSheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBottomSheet.d.ts","sourceRoot":"","sources":["../../../src/features/bottom-sheet/useBottomSheet.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGrE,oFAAoF;AACpF,wBAAgB,cAAc,IAAI,qBAAqB,CAQtD"}

package/dist/features/bottom-sheet/useBottomSheet.js

@@ -0,0 +1,11 @@
+import React from 'react';
+import { BottomSheetContext } from './BottomSheetContext';
+/*** Returns the shared bottom-sheet controller installed by BottomSheetProvider. */
+export function useBottomSheet() {
+    const controller = React.useContext(BottomSheetContext);
+    if (!controller) {
+        throw new Error('useBottomSheet must be used within BottomSheetProvider.');
+    }
+    return controller;
+}
+//# sourceMappingURL=useBottomSheet.js.map

package/dist/features/bottom-sheet/useBottomSheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBottomSheet.js","sourceRoot":"","sources":["../../../src/features/bottom-sheet/useBottomSheet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,oFAAoF;AACpF,MAAM,UAAU,cAAc;IAC5B,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAExD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC","sourcesContent":["import React from 'react';\n\nimport type { BottomSheetController } from '../../types/bottomSheet';\nimport { BottomSheetContext } from './BottomSheetContext';\n\n/*** Returns the shared bottom-sheet controller installed by BottomSheetProvider. */\nexport function useBottomSheet(): BottomSheetController {\n  const controller = React.useContext(BottomSheetContext);\n\n  if (!controller) {\n    throw new Error('useBottomSheet must be used within BottomSheetProvider.');\n  }\n\n  return controller;\n}\n"]}

package/dist/types/bottomSheet.d.ts

@@ -0,0 +1,18 @@
+import type React from 'react';
+export interface BottomSheetPresentOptions {
+    content: React.ReactNode;
+    snapPoints?: readonly (number | string)[];
+    initialIndex?: number;
+    enableDynamicSizing?: boolean;
+    enablePanDownToClose?: boolean;
+    dismissOnBackdropPress?: boolean;
+    keyboardBehavior?: 'extend' | 'fillParent' | 'interactive';
+    keyboardBlurBehavior?: 'none' | 'restore';
+    onIndexChange?: (index: number) => void;
+    onDismiss?: () => void;
+}
+export interface BottomSheetController {
+    present: (options: BottomSheetPresentOptions) => void;
+    dismiss: () => void;
+}
+//# sourceMappingURL=bottomSheet.d.ts.map

package/dist/types/bottomSheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bottomSheet.d.ts","sourceRoot":"","sources":["../../src/types/bottomSheet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;IAC3D,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,CAAC;IACtD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB"}

package/dist/types/bottomSheet.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bottomSheet.js.map

package/dist/types/bottomSheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bottomSheet.js","sourceRoot":"","sources":["../../src/types/bottomSheet.ts"],"names":[],"mappings":"","sourcesContent":["import type React from 'react';\n\nexport interface BottomSheetPresentOptions {\n  content: React.ReactNode;\n  snapPoints?: readonly (number | string)[];\n  initialIndex?: number;\n  enableDynamicSizing?: boolean;\n  enablePanDownToClose?: boolean;\n  dismissOnBackdropPress?: boolean;\n  keyboardBehavior?: 'extend' | 'fillParent' | 'interactive';\n  keyboardBlurBehavior?: 'none' | 'restore';\n  onIndexChange?: (index: number) => void;\n  onDismiss?: () => void;\n}\n\nexport interface BottomSheetController {\n  present: (options: BottomSheetPresentOptions) => void;\n  dismiss: () => void;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/surface",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Stable UI foundation for React Native and React Native Web.",
   "homepage": "https://github.com/ankhorage/surface#readme",
   "bugs": {
@@ -34,13 +34,17 @@
     "@react-native-vector-icons/material-design-icons": "^13.1.3",
     "react": "19.2.3",
     "react-native": "0.86.x",
+    "react-native-gesture-handler": "~2.32.0",
+    "react-native-reanimated": "4.5.1",
     "react-native-safe-area-context": "~5.7.0",
     "react-native-svg": "15.15.4",
-    "react-native-web": "~0.21.0"
+    "react-native-web": "~0.21.0",
+    "react-native-worklets": "0.10.1"
   },
   "dependencies": {
     "@ankhorage/color-theory": "^0.3.0",
-    "@ankhorage/contracts": "^12.0.1"
+    "@ankhorage/contracts": "^12.0.1",
+    "@gorhom/bottom-sheet": "^5.2.13"
   },
   "files": [
     "dist",
@@ -57,6 +61,13 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./bottom-sheet": {
+      "react-native": "./src/features/bottom-sheet/public.ts",
+      "browser": "./src/features/bottom-sheet/public.ts",
+      "types": "./dist/features/bottom-sheet/public.d.ts",
+      "import": "./dist/features/bottom-sheet/public.js",
+      "default": "./dist/features/bottom-sheet/public.js"
+    },
     "./theme": {
       "bun": "./src/theme/public.ts",
       "react-native": "./src/theme/public.ts",
@@ -102,9 +113,12 @@
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "react-native": "0.86.3",
+    "react-native-gesture-handler": "~2.32.0",
+    "react-native-reanimated": "4.5.1",
     "react-native-safe-area-context": "~5.7.0",
     "react-native-svg": "15.15.4",
     "react-native-web": "~0.21.0",
+    "react-native-worklets": "0.10.1",
     "typescript": "~6.0.3"
   },
   "packageManager": "bun@1.4.2"

package/src/features/bottom-sheet/BottomSheetContext.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+
+import type { BottomSheetController } from '../../types/bottomSheet';
+
+export const BottomSheetContext = React.createContext<BottomSheetController | null>(null);

package/src/features/bottom-sheet/BottomSheetProvider.tsx

@@ -0,0 +1,129 @@
+import {
+  BottomSheetBackdrop,
+  type BottomSheetBackdropProps,
+  BottomSheetModal,
+  BottomSheetModalProvider,
+  BottomSheetView,
+} from '@gorhom/bottom-sheet';
+import React from 'react';
+
+import type { BottomSheetController, BottomSheetPresentOptions } from '../../types/bottomSheet';
+import { BottomSheetContext } from './BottomSheetContext';
+
+/*** Installs the shared bottom-sheet modal host and controller for descendant consumers. */
+export function BottomSheetProvider({ children }: { children: React.ReactNode }) {
+  const modalRef = React.useRef<BottomSheetModal>(null);
+  const activeRequestRef = React.useRef<BottomSheetPresentOptions | null>(null);
+  const presentedRef = React.useRef(false);
+  const [activeRequest, setActiveRequest] = React.useState<BottomSheetPresentOptions | null>(null);
+
+  const present = React.useCallback((options: BottomSheetPresentOptions) => {
+    activeRequestRef.current = options;
+    setActiveRequest(options);
+  }, []);
+
+  const dismiss = React.useCallback(() => {
+    if (presentedRef.current) {
+      modalRef.current?.dismiss();
+      return;
+    }
+
+    const request = activeRequestRef.current;
+    activeRequestRef.current = null;
+    setActiveRequest(null);
+    request?.onDismiss?.();
+  }, []);
+
+  const handleDismiss = React.useCallback(() => {
+    const request = activeRequestRef.current;
+    presentedRef.current = false;
+    activeRequestRef.current = null;
+    setActiveRequest(null);
+    request?.onDismiss?.();
+  }, []);
+
+  const controller = React.useMemo<BottomSheetController>(
+    () => ({ dismiss, present }),
+    [dismiss, present],
+  );
+
+  return (
+    <BottomSheetContext.Provider value={controller}>
+      <BottomSheetModalProvider>
+        {children}
+        <BottomSheetHost
+          activeRequest={activeRequest}
+          handleDismiss={handleDismiss}
+          modalRef={modalRef}
+          presentedRef={presentedRef}
+        />
+      </BottomSheetModalProvider>
+    </BottomSheetContext.Provider>
+  );
+}
+
+interface BottomSheetHostProps {
+  readonly activeRequest: BottomSheetPresentOptions | null;
+  readonly handleDismiss: () => void;
+  readonly modalRef: React.RefObject<BottomSheetModal | null>;
+  readonly presentedRef: React.RefObject<boolean>;
+}
+
+/*** Renders and presents the single Gorhom modal owned by the provider. */
+function BottomSheetHost({
+  activeRequest,
+  handleDismiss,
+  modalRef,
+  presentedRef,
+}: BottomSheetHostProps) {
+  React.useEffect(() => {
+    if (!activeRequest || presentedRef.current) {
+      return;
+    }
+
+    presentedRef.current = true;
+    modalRef.current?.present();
+  }, [activeRequest, modalRef, presentedRef]);
+
+  const renderBackdrop = useBottomSheetBackdrop(activeRequest?.dismissOnBackdropPress);
+  const snapPoints = React.useMemo(
+    () => (activeRequest?.snapPoints ? [...activeRequest.snapPoints] : undefined),
+    [activeRequest?.snapPoints],
+  );
+
+  if (!activeRequest) {
+    return null;
+  }
+
+  return (
+    <BottomSheetModal
+      ref={modalRef}
+      backdropComponent={renderBackdrop}
+      enableDynamicSizing={activeRequest.enableDynamicSizing ?? true}
+      enablePanDownToClose={activeRequest.enablePanDownToClose ?? true}
+      index={activeRequest.initialIndex ?? 0}
+      keyboardBehavior={activeRequest.keyboardBehavior ?? 'interactive'}
+      keyboardBlurBehavior={activeRequest.keyboardBlurBehavior ?? 'restore'}
+      onChange={activeRequest.onIndexChange}
+      onDismiss={handleDismiss}
+      snapPoints={snapPoints}
+    >
+      <BottomSheetView>{activeRequest.content}</BottomSheetView>
+    </BottomSheetModal>
+  );
+}
+
+/*** Creates the backdrop renderer for the active bottom-sheet request. */
+function useBottomSheetBackdrop(dismissOnBackdropPress: boolean | undefined) {
+  return React.useCallback(
+    (props: BottomSheetBackdropProps) => (
+      <BottomSheetBackdrop
+        {...props}
+        appearsOnIndex={0}
+        disappearsOnIndex={-1}
+        pressBehavior={dismissOnBackdropPress === false ? 'none' : 'close'}
+      />
+    ),
+    [dismissOnBackdropPress],
+  );
+}

package/src/features/bottom-sheet/public.ts

@@ -0,0 +1,3 @@
+export type { BottomSheetController, BottomSheetPresentOptions } from '../../types/bottomSheet';
+export { BottomSheetProvider } from './BottomSheetProvider';
+export { useBottomSheet } from './useBottomSheet';

package/src/features/bottom-sheet/useBottomSheet.test.tsx

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'bun:test';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import { useBottomSheet } from './useBottomSheet';
+
+describe('useBottomSheet', () => {
+  it('requires BottomSheetProvider', () => {
+    function Consumer() {
+      useBottomSheet();
+      return null;
+    }
+
+    expect(() => renderToStaticMarkup(<Consumer />)).toThrow(
+      'useBottomSheet must be used within BottomSheetProvider.',
+    );
+  });
+});

package/src/features/bottom-sheet/useBottomSheet.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+
+import type { BottomSheetController } from '../../types/bottomSheet';
+import { BottomSheetContext } from './BottomSheetContext';
+
+/*** Returns the shared bottom-sheet controller installed by BottomSheetProvider. */
+export function useBottomSheet(): BottomSheetController {
+  const controller = React.useContext(BottomSheetContext);
+
+  if (!controller) {
+    throw new Error('useBottomSheet must be used within BottomSheetProvider.');
+  }
+
+  return controller;
+}

package/src/index.test.ts

@@ -9,6 +9,7 @@ const indexSource = readFileSync(new URL('./index.ts', import.meta.url), 'utf8')
 const packageJson = JSON.parse(
   readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
 ) as {
+  dependencies: Record<string, string>;
   devDependencies: Record<string, string>;
   exports: Record<string, unknown>;
   files: string[];
@@ -80,7 +81,7 @@ describe('public root barrel contract', () => {
 });
 
 describe('public package metadata contract', () => {
-  it('keeps package metadata aligned with the single-entry public surface', () => {
+  it('keeps package metadata aligned with deliberate public entrypoints', () => {
     expect(packageJson.files).toEqual(['dist', 'src', 'README.md', 'CHANGELOG.md', 'LICENSE']);
     expect(packageJson.exports).toEqual({
       '.': {
@@ -90,6 +91,13 @@ describe('public package metadata contract', () => {
         import: './dist/index.js',
         types: './dist/index.d.ts',
       },
+      './bottom-sheet': {
+        'react-native': './src/features/bottom-sheet/public.ts',
+        browser: './src/features/bottom-sheet/public.ts',
+        default: './dist/features/bottom-sheet/public.js',
+        import: './dist/features/bottom-sheet/public.js',
+        types: './dist/features/bottom-sheet/public.d.ts',
+      },
       './theme': {
         bun: './src/theme/public.ts',
         'react-native': './src/theme/public.ts',
@@ -109,3 +117,12 @@ describe('public package metadata contract', () => {
     expect(packageJson.devDependencies['react-native-svg']).toBe('15.15.4');
   });
 });
+
+describe('bottom-sheet package contract', () => {
+  it('keeps the implementation and Expo 57 runtime boundary explicit', () => {
+    expect(packageJson.dependencies['@gorhom/bottom-sheet']).toMatch(/^\^5\./);
+    expect(packageJson.peerDependencies['react-native-gesture-handler']).toMatch(/^~2\.32\./);
+    expect(packageJson.peerDependencies['react-native-reanimated']).toBe('4.5.1');
+    expect(packageJson.peerDependencies['react-native-worklets']).toBe('0.10.1');
+  });
+});

package/src/types/bottomSheet.ts

@@ -0,0 +1,19 @@
+import type React from 'react';
+
+export interface BottomSheetPresentOptions {
+  content: React.ReactNode;
+  snapPoints?: readonly (number | string)[];
+  initialIndex?: number;
+  enableDynamicSizing?: boolean;
+  enablePanDownToClose?: boolean;
+  dismissOnBackdropPress?: boolean;
+  keyboardBehavior?: 'extend' | 'fillParent' | 'interactive';
+  keyboardBlurBehavior?: 'none' | 'restore';
+  onIndexChange?: (index: number) => void;
+  onDismiss?: () => void;
+}
+
+export interface BottomSheetController {
+  present: (options: BottomSheetPresentOptions) => void;
+  dismiss: () => void;
+}