react-modal-sheet 5.1.1 → 5.2.0

package/README.md

@@ -448,6 +448,82 @@ The scroll state provides:
 - `scrollPosition`: `'top'`, `'bottom'`, `'middle'`, or `undefined`
 - `currentSnap`: Current snap point index (if using snap points)
 
+#### Creating custom scrollers
+
+If you need more control over the scrollable area, eg. when you don't want the whole content area to be scrollable, you can disable the default scrolling behavior of the `Sheet.Content` and implement your own scroller with the help of `useScrollPosition` and `useVirtualKeyboard` utility hooks.
+
+> [!NOTE]
+> These hooks are internally used by the `Sheet.Content` component so you shouldn't need to use them unless you are implementing a custom scroller. However they are general purpose hooks so you can use them in other parts of your app as well if you want 😊
+
+```tsx
+import {
+  Sheet,
+  useScrollPosition,
+  useVirtualKeyboard,
+} from 'react-modal-sheet';
+
+function CustomScrollerExample() {
+  const [isOpen, setOpen] = useState(false);
+
+  const { scrollRef, scrollPosition } = useScrollPosition({
+    isEnabled: isOpen,
+  });
+
+  const { keyboardHeight } = useVirtualKeyboard({
+    isEnabled: isOpen,
+  });
+
+  /**
+   * If you use `var(--keyboard-inset-height)` CSS variable you can just call
+   * `useVirtualKeyboard()` without destructuring anything from it:
+   *
+   * useVirtualKeyboard({ isEnabled: isOpen });
+   */
+
+  return (
+    // Disable default keyboard avoidance
+    <Sheet avoidKeyboard={false} isOpen={isOpen} onClose={() => setOpen(false)}>
+      <Sheet.Container>
+        <Sheet.Header />
+        <Sheet.Content
+          // Disable default scrolling
+          disableScroll
+          // Dragging is still managed by `Sheet.Content` so we control it here
+          disableDrag={scrollPosition !== 'top'}
+        >
+          <div
+            style={{
+              // Use CSS variable managed by `useVirtualKeyboard`
+              paddingBottom: 'var(--keyboard-inset-height)',
+              // Alternatively manually apply keyboard padding
+              paddingBottom: keyboardHeight,
+              // Some layout styles for custom content
+              height: '100%',
+              display: 'grid',
+              gridTemplateRows: 'auto 1fr auto',
+            }}
+          >
+            <div>Some content here...</div>
+
+            <div
+              // Pass ref to the custom scroller so we can track its scroll position
+              ref={scrollRef}
+              // Make it scrollable
+              style={{ overflowY: 'auto' }}
+            >
+              <div style={{ height: '400vh' }}>Long content here...</div>
+            </div>
+
+            <div>More content here...</div>
+          </div>
+        </Sheet.Content>
+      </Sheet.Container>
+      <Sheet.Backdrop />
+    </Sheet>
+  );
+}
+```
+
 ### 🪟 iOS Modal View effect
 
 In addition to the `Sheet.Backdrop` it's possible to apply a scaling effect to the main app element to highlight the modality of the bottom sheet. This effect mimics the [iOS Modal View](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/modality/) presentation style to bring more focus to the sheet and add some delight to the user experience.
@@ -778,3 +854,41 @@ If you're experiencing issues after upgrading, check the "What's new in v5" sect
 1. **Snap points not working**: Ensure your snap points are in ascending order (`[0, 0.5, 1]` instead of `[1, 0.5, 0]`)
 2. **Scrolling issues**: Remove `Sheet.Scroller` components as scrolling is now handled by `Sheet.Content`
 3. **Detent errors**: Update detent prop values (`"full-height"` → `"default"`, `"content-height"` → `"content"`)
+
+## 🤝 Contributing
+
+If you find a bug or have a feature request please open an issue. If you want to contribute code please open a pull request.
+
+You can build and run the library and the example app locally like this:
+
+1. First install [yalc](https://github.com/wclr/yalc) globally for managing local package dependencies.
+
+```sh
+npm i yalc -g
+```
+
+2. Install deps + configure yalc.
+
+```sh
+npm install
+npm run build
+npm run link
+```
+
+3. Start a watcher for building the library.
+
+```sh
+npm run dev
+```
+
+4. Run dev server for the example app (do this in another terminal).
+
+```sh
+cd example
+npm run dev
+```
+
+5. Open http://localhost:5173/ to see the examples. Now if you make edits to the library code the example app will automatically refresh.
+
+> [!TIP]
+> If you want to test the example app on your phone you can run the example app with `npm run dev:host` and then open your computer's local IP address in your phone's browser. Make sure your phone is on the same network as your computer.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { EasingDefinition, motion, MotionValue } from 'motion/react';
-import { ForwardRefExoticComponent, ReactNode, ComponentPropsWithoutRef, RefAttributes, FunctionComponent, HTMLAttributes, RefObject } from 'react';
+import { ForwardRefExoticComponent, ReactNode, ComponentPropsWithoutRef, RefAttributes, FunctionComponent, HTMLAttributes, RefObject, CSSProperties } from 'react';
 
 type SheetDetent = 'default' | 'full' | 'content';
 type CommonProps = {
@@ -47,6 +47,8 @@ type SheetContentProps = MotionCommonProps & CommonProps & {
     disableDrag?: boolean | ((args: SheetStateInfo) => boolean);
     disableScroll?: boolean | ((args: SheetStateInfo) => boolean);
     scrollRef?: RefObject<HTMLDivElement | null>;
+    scrollClassName?: string;
+    scrollStyle?: CSSProperties;
 };
 type SheetBackdropProps = MotionCommonProps & CommonProps;
 type SheetDragIndicatorProps = HTMLAttributes<HTMLDivElement> & CommonProps;
@@ -73,6 +75,112 @@ interface SheetCompoundComponent {
 }
 type SheetCompound = SheetComponent & SheetCompoundComponent;
 
+type UseScrollPositionOptions = {
+    /**
+     * Debounce delay in ms for scroll event handling.
+     * @default 32
+     */
+    debounceDelay?: number;
+    /**
+     * Enable or disable the hook entirely.
+     * @default true
+     */
+    isEnabled?: boolean;
+};
+/**
+ * Hook to track the scroll position of an element.
+ *
+ * The scroll position can be 'top', 'bottom', 'middle', or undefined if the content is not scrollable.
+ * The hook provides a `scrollRef` callback to assign to the scrollable element.
+ *
+ * Note that the scroll position is only updated when the user stops scrolling
+ * for a short moment (debounced). You can set `debounceDelay` to `0` to disable debouncing entirely.
+ *
+ * @param options Configuration options for the hook.
+ * @returns An object containing the `scrollRef` callback and the current `scrollPosition`.
+ *
+ * @example
+ * ```tsx
+ * import { useScrollPosition } from 'react-modal-sheet';
+ *
+ * function MyComponent() {
+ *   const { scrollRef, scrollPosition } = useScrollPosition();
+ *
+ *   return (
+ *     <div>
+ *       <p>Scroll position: {scrollPosition}</p>
+ *       <div ref={scrollRef} style={{ overflowY: 'auto', maxHeight: '300px' }}>
+ *         ...long content...
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useScrollPosition(options?: UseScrollPositionOptions): {
+    scrollRef: (element: HTMLElement | null) => void;
+    scrollPosition: "top" | "bottom" | "middle" | undefined;
+};
+
+type UseVirtualKeyboardOptions = {
+    /**
+     * Ref to the container element to apply `keyboard-inset-height` CSS variable updates.
+     * @default document.documentElement
+     */
+    containerRef?: RefObject<HTMLElement | null>;
+    /**
+     * Enable or disable the hook entirely.
+     * @default true
+     */
+    isEnabled?: boolean;
+    /**
+     * Minimum pixel height difference to consider the keyboard visible.
+     * @default 100
+     */
+    visualViewportThreshold?: number;
+    /**
+     * Whether to treat contenteditable elements as text inputs.
+     * @default true
+     */
+    includeContentEditable?: boolean;
+    /**
+     * Delay in ms for debouncing viewport changes.
+     * @default 100
+     */
+    debounceDelay?: number;
+};
+/**
+ * A hook that detects virtual keyboard visibility and height.
+ * It listens to focus events and visual viewport changes to determine
+ * if a text input is focused and the keyboard is likely visible.
+ *
+ * It also sets the `--keyboard-inset-height` CSS variable on the specified container
+ * (or `:root` by default) to allow for easy styling adjustments when the keyboard is open.
+ *
+ * @param options Configuration options for the hook.
+ * @returns An object containing `isKeyboardOpen` and `keyboardHeight`.
+ *
+ * @example
+ * ```tsx
+ * import { useVirtualKeyboard } from 'react-modal-sheet';
+ *
+ * function MyComponent() {
+ *   const { isKeyboardOpen, keyboardHeight } = useVirtualKeyboard();
+ *
+ *   return (
+ *     <div>
+ *       <p>Keyboard is {isKeyboardOpen ? 'open' : 'closed'}</p>
+ *       <p>Keyboard height: {keyboardHeight}px</p>
+ *    </div>
+ *  );
+ * }
+ * ```
+ */
+declare function useVirtualKeyboard(options?: UseVirtualKeyboardOptions): {
+    keyboardHeight: number;
+    isKeyboardOpen: boolean;
+};
+
 interface SheetRef {
     y: MotionValue<number>;
     yInverted: MotionValue<number>;
@@ -81,4 +189,4 @@ interface SheetRef {
 }
 declare const Sheet: SheetCompound;
 
-export { Sheet, type SheetBackdropProps, type SheetContainerProps, type SheetContentProps, type SheetDetent, type SheetDragIndicatorProps, type SheetHeaderProps, type SheetProps, type SheetRef, type SheetSnapPoint, type SheetStateInfo, type SheetTweenConfig };
+export { Sheet, type SheetBackdropProps, type SheetContainerProps, type SheetContentProps, type SheetDetent, type SheetDragIndicatorProps, type SheetHeaderProps, type SheetProps, type SheetRef, type SheetSnapPoint, type SheetStateInfo, type SheetTweenConfig, useScrollPosition, useVirtualKeyboard };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { EasingDefinition, motion, MotionValue } from 'motion/react';
-import { ForwardRefExoticComponent, ReactNode, ComponentPropsWithoutRef, RefAttributes, FunctionComponent, HTMLAttributes, RefObject } from 'react';
+import { ForwardRefExoticComponent, ReactNode, ComponentPropsWithoutRef, RefAttributes, FunctionComponent, HTMLAttributes, RefObject, CSSProperties } from 'react';
 
 type SheetDetent = 'default' | 'full' | 'content';
 type CommonProps = {
@@ -47,6 +47,8 @@ type SheetContentProps = MotionCommonProps & CommonProps & {
     disableDrag?: boolean | ((args: SheetStateInfo) => boolean);
     disableScroll?: boolean | ((args: SheetStateInfo) => boolean);
     scrollRef?: RefObject<HTMLDivElement | null>;
+    scrollClassName?: string;
+    scrollStyle?: CSSProperties;
 };
 type SheetBackdropProps = MotionCommonProps & CommonProps;
 type SheetDragIndicatorProps = HTMLAttributes<HTMLDivElement> & CommonProps;
@@ -73,6 +75,112 @@ interface SheetCompoundComponent {
 }
 type SheetCompound = SheetComponent & SheetCompoundComponent;
 
+type UseScrollPositionOptions = {
+    /**
+     * Debounce delay in ms for scroll event handling.
+     * @default 32
+     */
+    debounceDelay?: number;
+    /**
+     * Enable or disable the hook entirely.
+     * @default true
+     */
+    isEnabled?: boolean;
+};
+/**
+ * Hook to track the scroll position of an element.
+ *
+ * The scroll position can be 'top', 'bottom', 'middle', or undefined if the content is not scrollable.
+ * The hook provides a `scrollRef` callback to assign to the scrollable element.
+ *
+ * Note that the scroll position is only updated when the user stops scrolling
+ * for a short moment (debounced). You can set `debounceDelay` to `0` to disable debouncing entirely.
+ *
+ * @param options Configuration options for the hook.
+ * @returns An object containing the `scrollRef` callback and the current `scrollPosition`.
+ *
+ * @example
+ * ```tsx
+ * import { useScrollPosition } from 'react-modal-sheet';
+ *
+ * function MyComponent() {
+ *   const { scrollRef, scrollPosition } = useScrollPosition();
+ *
+ *   return (
+ *     <div>
+ *       <p>Scroll position: {scrollPosition}</p>
+ *       <div ref={scrollRef} style={{ overflowY: 'auto', maxHeight: '300px' }}>
+ *         ...long content...
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useScrollPosition(options?: UseScrollPositionOptions): {
+    scrollRef: (element: HTMLElement | null) => void;
+    scrollPosition: "top" | "bottom" | "middle" | undefined;
+};
+
+type UseVirtualKeyboardOptions = {
+    /**
+     * Ref to the container element to apply `keyboard-inset-height` CSS variable updates.
+     * @default document.documentElement
+     */
+    containerRef?: RefObject<HTMLElement | null>;
+    /**
+     * Enable or disable the hook entirely.
+     * @default true
+     */
+    isEnabled?: boolean;
+    /**
+     * Minimum pixel height difference to consider the keyboard visible.
+     * @default 100
+     */
+    visualViewportThreshold?: number;
+    /**
+     * Whether to treat contenteditable elements as text inputs.
+     * @default true
+     */
+    includeContentEditable?: boolean;
+    /**
+     * Delay in ms for debouncing viewport changes.
+     * @default 100
+     */
+    debounceDelay?: number;
+};
+/**
+ * A hook that detects virtual keyboard visibility and height.
+ * It listens to focus events and visual viewport changes to determine
+ * if a text input is focused and the keyboard is likely visible.
+ *
+ * It also sets the `--keyboard-inset-height` CSS variable on the specified container
+ * (or `:root` by default) to allow for easy styling adjustments when the keyboard is open.
+ *
+ * @param options Configuration options for the hook.
+ * @returns An object containing `isKeyboardOpen` and `keyboardHeight`.
+ *
+ * @example
+ * ```tsx
+ * import { useVirtualKeyboard } from 'react-modal-sheet';
+ *
+ * function MyComponent() {
+ *   const { isKeyboardOpen, keyboardHeight } = useVirtualKeyboard();
+ *
+ *   return (
+ *     <div>
+ *       <p>Keyboard is {isKeyboardOpen ? 'open' : 'closed'}</p>
+ *       <p>Keyboard height: {keyboardHeight}px</p>
+ *    </div>
+ *  );
+ * }
+ * ```
+ */
+declare function useVirtualKeyboard(options?: UseVirtualKeyboardOptions): {
+    keyboardHeight: number;
+    isKeyboardOpen: boolean;
+};
+
 interface SheetRef {
     y: MotionValue<number>;
     yInverted: MotionValue<number>;
@@ -81,4 +189,4 @@ interface SheetRef {
 }
 declare const Sheet: SheetCompound;
 
-export { Sheet, type SheetBackdropProps, type SheetContainerProps, type SheetContentProps, type SheetDetent, type SheetDragIndicatorProps, type SheetHeaderProps, type SheetProps, type SheetRef, type SheetSnapPoint, type SheetStateInfo, type SheetTweenConfig };
+export { Sheet, type SheetBackdropProps, type SheetContainerProps, type SheetContentProps, type SheetDetent, type SheetDragIndicatorProps, type SheetHeaderProps, type SheetProps, type SheetRef, type SheetSnapPoint, type SheetStateInfo, type SheetTweenConfig, useScrollPosition, useVirtualKeyboard };

package/dist/index.js

@@ -188,6 +188,21 @@ var isIPad = cached(function() {
 var isIOS = cached(function() {
   return isIPhone() || isIPad();
 });
+function waitForElement(className, interval = 50, maxAttempts = 20) {
+  return new Promise((resolve) => {
+    let attempts = 0;
+    const timer = setInterval(() => {
+      const element = document.getElementsByClassName(
+        className
+      )[0];
+      attempts++;
+      if (element || attempts >= maxAttempts) {
+        clearInterval(timer);
+        resolve(element);
+      }
+    }, interval);
+  });
+}
 
 // src/SheetBackdrop.tsx
 var isClickable = (props) => !!props.onClick || !!props.onTap;
@@ -262,12 +277,12 @@ function useDragConstraints() {
   const onMeasure = React4.useCallback(() => constraints, []);
   return { ref, onMeasure };
 }
-function useScrollPosition() {
-  const ref = React4.useRef(null);
+function useScrollPosition(options = {}) {
+  const { debounceDelay = 32, isEnabled = true } = options;
+  const [element, setElement] = React4.useState(null);
   const [scrollPosition, setScrollPosition] = React4.useState(void 0);
   React4.useEffect(() => {
-    const element = ref.current;
-    if (!element) return;
+    if (!element || !isEnabled) return;
     let scrollTimeout = null;
     function determineScrollPosition(element2) {
       const { scrollTop, scrollHeight, clientHeight } = element2;
@@ -290,14 +305,21 @@ function useScrollPosition() {
       setScrollPosition(position);
     }
     function onScroll(event) {
-      if (event.currentTarget instanceof HTMLDivElement) {
+      if (event.currentTarget instanceof HTMLElement) {
         const el = event.currentTarget;
         if (scrollTimeout) clearTimeout(scrollTimeout);
-        scrollTimeout = setTimeout(() => determineScrollPosition(el), 32);
+        if (debounceDelay === 0) {
+          determineScrollPosition(el);
+        } else {
+          scrollTimeout = setTimeout(
+            () => determineScrollPosition(el),
+            debounceDelay
+          );
+        }
       }
     }
     function onTouchStart(event) {
-      if (event.currentTarget instanceof HTMLDivElement) {
+      if (event.currentTarget instanceof HTMLElement) {
         determineScrollPosition(event.currentTarget);
       }
     }
@@ -309,8 +331,11 @@ function useScrollPosition() {
       element.removeEventListener("scroll", onScroll);
       element.removeEventListener("touchstart", onTouchStart);
     };
-  }, []);
-  return { ref, scrollPosition };
+  }, [element, isEnabled]);
+  return {
+    scrollRef: (element2) => setElement(element2),
+    scrollPosition
+  };
 }
 
 // src/SheetContent.tsx
@@ -321,6 +346,8 @@ var SheetContent = React4.forwardRef(
     children,
     style: styleProp,
     className = "",
+    scrollClassName = "",
+    scrollStyle: scrollStyleProp,
     scrollRef: scrollRefProp = null,
     unstyled,
     ...rest
@@ -365,9 +392,9 @@ var SheetContent = React4.forwardRef(
       /* @__PURE__ */ React4__default.default.createElement(
         react.motion.div,
         {
-          ref: mergeRefs([scroll.ref, scrollRefProp]),
-          style: scrollStyle,
-          className: "react-modal-sheet-content-scroller"
+          ref: mergeRefs([scroll.scrollRef, scrollRefProp]),
+          style: { ...scrollStyle, ...scrollStyleProp },
+          className: `react-modal-sheet-content-scroller ${scrollClassName}`
         },
         children
       )
@@ -865,13 +892,14 @@ function useSheetState({
   }, [state]);
   return state;
 }
-function useVirtualKeyboard({
-  containerRef,
-  isEnabled = true,
-  debounceDelay = 100,
-  includeContentEditable = true,
-  visualViewportThreshold = 100
-}) {
+function useVirtualKeyboard(options = {}) {
+  const {
+    containerRef,
+    isEnabled = true,
+    debounceDelay = 100,
+    includeContentEditable = true,
+    visualViewportThreshold = 100
+  } = options;
   const [state, setState] = React4.useState({
     isVisible: false,
     height: 0
@@ -886,11 +914,15 @@ function useVirtualKeyboard({
     const vv = window.visualViewport;
     const vk = navigator.virtualKeyboard;
     function setKeyboardInsetHeightEnv(height) {
-      var _a;
-      (_a = containerRef.current) == null ? void 0 : _a.style.setProperty(
-        "--keyboard-inset-height",
-        `${height}px`
-      );
+      const element = (containerRef == null ? void 0 : containerRef.current) || document.documentElement;
+      if (window.isSecureContext) {
+        element.style.setProperty(
+          "--keyboard-inset-height",
+          `env(keyboard-inset-height, ${height}px)`
+        );
+      } else {
+        element.style.setProperty("--keyboard-inset-height", `${height}px`);
+      }
     }
     function handleFocusIn(e) {
       if (e.target instanceof HTMLElement && isTextInput(e.target)) {
@@ -968,8 +1000,20 @@ function computeSnapPoints({
   snapPointsProp,
   sheetHeight
 }) {
+  if (snapPointsProp[0] !== 0) {
+    console.error(
+      `First snap point should be 0 to ensure the sheet can be fully closed. Got: [${snapPointsProp.join(", ")}]`
+    );
+    snapPointsProp.unshift(0);
+  }
+  if (snapPointsProp[snapPointsProp.length - 1] !== 1) {
+    console.error(
+      `Last snap point should be 1 to ensure the sheet can be fully opened. Got: [${snapPointsProp.join(", ")}]`
+    );
+    snapPointsProp.push(1);
+  }
   if (sheetHeight <= 0) {
-    console.warn(
+    console.error(
       `Sheet height is ${sheetHeight}, cannot compute snap points. Make sure the sheet is mounted and has a valid height.`
     );
     return [];
@@ -1263,6 +1307,7 @@ var Sheet = React4.forwardRef(
       isOpen,
       onOpen: async () => {
         onOpenStart == null ? void 0 : onOpenStart();
+        await waitForElement("react-modal-sheet-container");
         const initialSnapPoint = initialSnap !== void 0 ? getSnapPoint(initialSnap) : null;
         const yTo = (initialSnapPoint == null ? void 0 : initialSnapPoint.snapValueY) ?? 0;
         await react.animate(y, yTo, animationOptions);
@@ -1330,5 +1375,7 @@ var Sheet2 = Object.assign(Sheet, {
 });
 
 exports.Sheet = Sheet2;
+exports.useScrollPosition = useScrollPosition;
+exports.useVirtualKeyboard = useVirtualKeyboard;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map