react-modal-sheet 5.1.2 → 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.

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

@@ -277,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;
@@ -305,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);
       }
     }
@@ -324,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
@@ -336,6 +346,8 @@ var SheetContent = React4.forwardRef(
     children,
     style: styleProp,
     className = "",
+    scrollClassName = "",
+    scrollStyle: scrollStyleProp,
     scrollRef: scrollRefProp = null,
     unstyled,
     ...rest
@@ -380,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
       )
@@ -880,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
@@ -901,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)) {
@@ -1358,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