react-native-nitro-modal 0.2.0 → 0.3.1-rc

package/src/NitroModal.nitro.ts

@@ -13,13 +13,20 @@ import type {
 export type ModalMode = 'bottomSheet' | 'popup';
 
 /**
- * Resting heights of a `bottomSheet`.
+ * Named resting heights of a `bottomSheet`.
  * - `small`: ~25% of the available height.
  * - `medium`: ~50% of the available height.
  * - `large`: the full available height.
  * - `fitContent`: the measured height of the React content.
  */
-export type SheetDetent = 'small' | 'medium' | 'large' | 'fitContent';
+export type NamedSheetDetent = 'small' | 'medium' | 'large' | 'fitContent';
+
+/**
+ * A resting height of a `bottomSheet`: a named height, or the height
+ * (dp/pt) of the content above the bottom safe area, clamped to the
+ * available height.
+ */
+export type SheetDetent = NamedSheetDetent | number;
 
 /**
  * How the modal reacts to the software keyboard.
@@ -48,6 +55,12 @@ export interface NitroModalProps extends HybridViewProps {
   /** Whether the modal should be presented. */
   isOpen: boolean;
   mode: ModalMode;
+  /**
+   * A `bottomSheet` that lives inside the host view's own bounds instead of
+   * being presented over the app: no backdrop, touches outside the sheet
+   * reach the views behind it, and the user can't dismiss it.
+   */
+  isInline: boolean;
   /** Detents of a `bottomSheet`, smallest first. At most 3 are used on Android. */
   detents: SheetDetent[];
   /** Index into `detents` that the sheet opens at. */
@@ -68,6 +81,19 @@ export interface NitroModalProps extends HybridViewProps {
   contentBackgroundColor?: number;
   keyboardBehavior: KeyboardBehavior;
   popupAnimation: PopupAnimation;
+  /**
+   * Pulling a `bottomSheet` down past its lowest detent calls
+   * `onPullToRefresh`. Needs `dismissOnSwipe` off (always the case inline).
+   */
+  pullToRefreshEnabled: boolean;
+  /**
+   * A refresh is in progress: the sheet rests pulled down below its lowest
+   * detent with an activity indicator above it. Native starts refreshing on
+   * its own when a pull is released. `undefined` shows no indicator.
+   */
+  refreshing?: boolean;
+  /** Refresh indicator color as a processed ARGB color. Omit for the platform default. */
+  refreshIndicatorColor?: number;
 
   /** The present transition finished. */
   onPresent?: () => void;
@@ -80,6 +106,16 @@ export interface NitroModalProps extends HybridViewProps {
   onBackButtonPress?: () => void;
   /** The area available to the content changed (rotation, keyboard, sheet sizing). */
   onContentAreaChange?: (area: ModalContentArea) => void;
+  /**
+   * The user pulled the sheet down past its lowest detent and let go. The
+   * gesture must start with the sheet resting on that detent.
+   */
+  onPullToRefresh?: () => void;
+  /**
+   * Inline sheets: where the sheet's top rests within the host view (or
+   * will, once it settles). Lets React lay the content out where it is shown.
+   */
+  onRestingTopChange?: (top: number) => void;
 }
 
 export interface NitroModalMethods extends HybridViewMethods {

package/src/NitroModal.tsx

@@ -1,4 +1,5 @@
 import {
+  useEffect,
   useImperativeHandle,
   useLayoutEffect,
   useMemo,
@@ -21,12 +22,22 @@ import type {
   KeyboardBehavior,
   ModalContentArea,
   ModalMode,
+  NamedSheetDetent,
   NitroModal as NitroModalHybridView,
   PopupAnimation,
   SheetDetent,
 } from './NitroModal.nitro';
 import { callback, NitroModalView } from './NitroModalView';
 
+/**
+ * Where a `bottomSheet` lives.
+ * - `modal`: presented over the whole app, with a backdrop.
+ * - `inline`: inside the component's own frame (`style`), as part of your
+ *   screen. No backdrop, the views behind it stay interactive, and the user
+ *   can't dismiss it.
+ */
+export type ModalPresentation = 'modal' | 'inline';
+
 export interface NitroModalRef {
   /** Opens the modal. Only for uncontrolled usage (no `isOpen` prop). */
   present(): void;
@@ -45,7 +56,23 @@ export interface NitroModalProps {
   isOpen?: boolean;
   /** @default 'bottomSheet' */
   mode?: ModalMode;
-  /** Sheet heights, smallest first. Android uses at most three. @default ['fitContent'] */
+  /**
+   * `inline` keeps a `bottomSheet` inside this component's frame, like a
+   * persistent sheet that is part of the screen. Popups are always modal.
+   * @default 'modal'
+   */
+  presentation?: ModalPresentation;
+  /**
+   * Inline only: the frame the sheet lives in, laid out like any view.
+   * The sheet rests against its bottom edge and its largest detent reaches its
+   * top edge. @default StyleSheet.absoluteFill
+   */
+  style?: StyleProp<ViewStyle>;
+  /**
+   * Sheet heights, smallest first: named sizes, or the content height in
+   * dp/pt above the bottom safe area. Android uses at most three.
+   * @default ['fitContent']
+   */
   detents?: SheetDetent[];
   /** @default 0 */
   initialDetentIndex?: number;
@@ -78,6 +105,22 @@ export interface NitroModalProps {
   onDetentChange?: (index: number) => void;
   onBackdropPress?: () => void;
   onBackButtonPress?: () => void;
+  /**
+   * Pull-to-refresh: the user dragged the sheet down past its lowest detent
+   * and let go. Only for sheets that can't be swiped away (inline, or
+   * `dismissOnSwipe={false}`), and only from a gesture that starts with the
+   * sheet resting on its lowest detent.
+   */
+  onPullToRefresh?: () => void;
+  /**
+   * Whether a refresh is in progress, like `RefreshControl`'s `refreshing`.
+   * While true, the sheet stays pulled down below its lowest detent with an
+   * activity indicator above it. Set it to `true` in `onPullToRefresh` and
+   * back to `false` when done. Leave undefined to show no indicator.
+   */
+  refreshing?: boolean;
+  /** Color of the refresh indicator. Defaults to the platform style. */
+  refreshIndicatorColor?: ColorValue;
   children?: ReactNode;
   testID?: string;
   ref?: Ref<NitroModalRef>;
@@ -86,6 +129,13 @@ export interface NitroModalProps {
 const DEFAULT_DETENTS: SheetDetent[] = ['fitContent'];
 const BLACK = 0xff000000;
 
+function parseDetent(value: string): SheetDetent {
+  const points = Number(value);
+  return value !== '' && Number.isFinite(points)
+    ? points
+    : (value as NamedSheetDetent);
+}
+
 function toNativeColor(color: ColorValue | undefined): number | undefined {
   if (color == null) return undefined;
   const processed = processColor(color);
@@ -96,6 +146,8 @@ function toNativeColor(color: ColorValue | undefined): number | undefined {
 export function NitroModal({
   isOpen,
   mode = 'bottomSheet',
+  presentation = 'modal',
+  style,
   detents = DEFAULT_DETENTS,
   initialDetentIndex = 0,
   backdropColor = 'black',
@@ -115,11 +167,15 @@ export function NitroModal({
   onDetentChange,
   onBackdropPress,
   onBackButtonPress,
+  onPullToRefresh,
+  refreshing,
+  refreshIndicatorColor,
   children,
   testID,
   ref,
 }: NitroModalProps) {
   const isControlled = isOpen !== undefined;
+  const isInline = presentation === 'inline' && mode === 'bottomSheet';
   const [internalOpen, setInternalOpen] = useState(false);
   const open = isControlled ? isOpen : internalOpen;
 
@@ -134,26 +190,42 @@ export function NitroModal({
   const renderContent = open || sessionActive;
 
   const [area, setArea] = useState<ModalContentArea | null>(null);
+  // Inline (iOS/Android): where the sheet's top rests in the host. The content
+  // is laid out there so `measure()`, which presses rely on, matches the
+  // screen; native cancels the offset out on screen.
+  const [restingTop, setRestingTop] = useState(0);
+  // Native starts refreshing as soon as a pull is released. Reporting `true`
+  // for the render that follows, then `refreshing` again, stops it if the
+  // handler didn't start a refresh (unchanged props never reach native).
+  const isRefreshControlled = refreshing !== undefined;
+  const [pullPending, setPullPending] = useState(false);
+  useEffect(() => {
+    if (pullPending) setPullPending(false);
+  }, [pullPending]);
   const hybridRef = useRef<NitroModalHybridView | null>(null);
 
   // Native callbacks are created once (stable props, no native updates on
   // re-render) and read the latest handlers from this ref.
   const latest = useRef({
     isControlled,
+    isRefreshControlled,
     onPresent,
     onDismiss,
     onDetentChange,
     onBackdropPress,
     onBackButtonPress,
+    onPullToRefresh,
   });
   useLayoutEffect(() => {
     latest.current = {
       isControlled,
+      isRefreshControlled,
       onPresent,
       onDismiss,
       onDetentChange,
       onBackdropPress,
       onBackButtonPress,
+      onPullToRefresh,
     };
   });
 
@@ -180,6 +252,13 @@ export function NitroModal({
       onBackButtonPress: callback(() => {
         latest.current.onBackButtonPress?.();
       }),
+      onPullToRefresh: callback(() => {
+        if (latest.current.isRefreshControlled) setPullPending(true);
+        latest.current.onPullToRefresh?.();
+      }),
+      onRestingTopChange: callback((top: number) => {
+        setRestingTop(top);
+      }),
       onContentAreaChange: callback((next: ModalContentArea) => {
         setArea((current) =>
           current?.width === next.width && current.height === next.height
@@ -220,7 +299,7 @@ export function NitroModal({
   // Arrays are diffed by identity, so keep one instance per distinct value.
   const detentsKey = detents.join(',');
   const nativeDetents = useMemo(
-    () => [...new Set(detentsKey.split(','))] as SheetDetent[],
+    () => [...new Set(detentsKey.split(','))].map(parseDetent),
     [detentsKey]
   );
 
@@ -240,9 +319,11 @@ export function NitroModal({
 
   return (
     <NitroModalView
-      style={styles.host}
+      style={isInline ? [StyleSheet.absoluteFill, style] : styles.host}
+      pointerEvents={isInline ? 'box-none' : undefined}
       isOpen={open}
       mode={mode}
+      isInline={isInline}
       detents={nativeDetents}
       initialDetentIndex={initialDetentIndex}
       backdropColor={toNativeColor(backdropColor) ?? BLACK}
@@ -256,13 +337,21 @@ export function NitroModal({
       contentBackgroundColor={toNativeColor(backgroundColor)}
       keyboardBehavior={keyboardBehavior}
       popupAnimation={popupAnimation}
+      pullToRefreshEnabled={onPullToRefresh != null}
+      refreshing={isRefreshControlled ? refreshing || pullPending : undefined}
+      refreshIndicatorColor={toNativeColor(refreshIndicatorColor)}
       {...nativeCallbacks}
     >
       {renderContent ? (
         <View
           collapsable={false}
           testID={testID}
-          style={[styles.container, containerStyle, contentContainerStyle]}
+          style={[
+            styles.container,
+            containerStyle,
+            contentContainerStyle,
+            isInline && restingTop > 0 ? { top: restingTop } : null,
+          ]}
         >
           {children}
         </View>

package/src/NitroModalView.web.tsx

@@ -1,19 +1,23 @@
 /// <reference lib="dom" />
 
 import {
+  useCallback,
   useLayoutEffect,
   useRef,
   useState,
   type CSSProperties,
   type ReactNode,
 } from 'react';
-import { Modal } from 'react-native';
+import { Modal, View, type StyleProp, type ViewStyle } from 'react-native';
 import type { ReactNativeView } from 'react-native-nitro-modules';
 import type { NitroModalMethods, NitroModalProps } from './NitroModal.nitro';
+import { clipOverflow, REFRESH_INDICATOR_SIZE } from './web/dom';
 import { ModalController } from './web/ModalController';
 
 interface WebNitroModalViewProps extends NitroModalProps {
   hybridRef?: (instance: NitroModalMethods) => void;
+  /** Inline: the frame the sheet fills. */
+  style?: StyleProp<ViewStyle>;
   children?: ReactNode;
 }
 
@@ -27,9 +31,13 @@ export function callback<T>(func: T): T {
  * Native Web's `Modal` (a portal with focus trapping, Escape handling and
  * stacking with other modals) and is laid out and animated by the presenters
  * in `./web`. In place, it renders nothing.
+ *
+ * An inline sheet renders in place instead: a view laid out with `style`,
+ * holding the sheet's elements.
  */
 function WebNitroModalView(props: WebNitroModalViewProps) {
   const { hybridRef, children } = props;
+  const isInline = props.isInline && props.mode === 'bottomSheet';
   const [mounted, setMounted] = useState(false);
   const [controller] = useState(() => new ModalController(setMounted));
   const overlay = useRef<HTMLDivElement>(null);
@@ -37,6 +45,8 @@ function WebNitroModalView(props: WebNitroModalViewProps) {
   const surface = useRef<HTMLDivElement>(null);
   const content = useRef<HTMLDivElement>(null);
   const grabber = useRef<HTMLDivElement>(null);
+  const refreshIndicator = useRef<HTMLDivElement>(null);
+  const refreshSpinner = useRef<HTMLDivElement>(null);
 
   useLayoutEffect(() => {
     controller.attach();
@@ -59,6 +69,8 @@ function WebNitroModalView(props: WebNitroModalViewProps) {
       surface: surface.current!,
       content: content.current!,
       grabber: grabber.current!,
+      refreshIndicator: refreshIndicator.current!,
+      refreshSpinner: refreshSpinner.current!,
     });
     return () => controller.elementsWillUnmount();
   }, [controller, mounted]);
@@ -69,10 +81,49 @@ function WebNitroModalView(props: WebNitroModalViewProps) {
     }
   });
 
-  if (!mounted) return null;
+  const hostRef = useCallback(
+    (node: unknown) => {
+      controller.hostDidChange(node instanceof HTMLElement ? node : null);
+    },
+    [controller]
+  );
 
   // Styles set here never change; the presenters write sizes, positions,
   // colors and animated values straight to the elements.
+  const layer = mounted ? (
+    // Focusable so the modal's focus trap lands here first rather than on the first input.
+    <div
+      ref={overlay}
+      tabIndex={-1}
+      style={
+        isInline
+          ? { ...styles.inlineOverlay, overflow: clipOverflow() }
+          : styles.overlay
+      }
+    >
+      <div ref={backdrop} aria-hidden style={styles.backdrop} />
+      <div ref={refreshIndicator} aria-hidden style={styles.refreshIndicator}>
+        <div ref={refreshSpinner} style={styles.refreshSpinner} />
+      </div>
+      <div ref={surface} style={styles.surface}>
+        <div ref={content} style={styles.content}>
+          {children}
+        </div>
+        <div ref={grabber} aria-hidden style={styles.grabber} />
+      </div>
+    </div>
+  ) : null;
+
+  if (isInline) {
+    return (
+      <View ref={hostRef} style={props.style} pointerEvents="box-none">
+        {layer}
+      </View>
+    );
+  }
+
+  if (!layer) return null;
+
   return (
     <Modal
       visible
@@ -80,16 +131,7 @@ function WebNitroModalView(props: WebNitroModalViewProps) {
       animationType="none"
       onRequestClose={controller.handleBackPress}
     >
-      {/* Focusable so the modal's focus trap lands here first rather than on the first input. */}
-      <div ref={overlay} tabIndex={-1} style={styles.overlay}>
-        <div ref={backdrop} aria-hidden style={styles.backdrop} />
-        <div ref={surface} style={styles.surface}>
-          <div ref={content} style={styles.content}>
-            {children}
-          </div>
-          <div ref={grabber} aria-hidden style={styles.grabber} />
-        </div>
-      </div>
+      {layer}
     </Modal>
   );
 }
@@ -100,6 +142,13 @@ const styles = {
     inset: 0,
     outline: 'none',
   },
+  // Fills the host view; the sheet hides below its bottom edge.
+  inlineOverlay: {
+    position: 'absolute',
+    inset: 0,
+    outline: 'none',
+    pointerEvents: 'none',
+  },
   backdrop: {
     position: 'absolute',
     inset: 0,
@@ -130,6 +179,24 @@ const styles = {
     backgroundColor: 'rgba(127, 127, 127, 0.4)',
     pointerEvents: 'none',
   },
+  refreshIndicator: {
+    position: 'absolute',
+    left: 0,
+    top: 0,
+    width: REFRESH_INDICATOR_SIZE,
+    height: REFRESH_INDICATOR_SIZE,
+    opacity: 0,
+    pointerEvents: 'none',
+  },
+  // Colored through `color` by the presenter.
+  refreshSpinner: {
+    width: '100%',
+    height: '100%',
+    boxSizing: 'border-box',
+    borderRadius: '50%',
+    border: '2.5px solid currentColor',
+    borderTopColor: 'transparent',
+  },
 } satisfies Record<string, CSSProperties>;
 
 export const NitroModalView = WebNitroModalView as unknown as ReactNativeView<

package/src/index.tsx

@@ -1,5 +1,6 @@
 export {
   NitroModal,
+  type ModalPresentation,
   type NitroModalProps,
   type NitroModalRef,
 } from './NitroModal';
@@ -7,6 +8,7 @@ export type {
   DismissReason,
   KeyboardBehavior,
   ModalMode,
+  NamedSheetDetent,
   PopupAnimation,
   SheetDetent,
 } from './NitroModal.nitro';

package/src/web/AnimatedValue.ts

@@ -71,6 +71,10 @@ export class AnimatedValue {
     return this.current;
   }
 
+  get isAnimating(): boolean {
+    return this.run != null;
+  }
+
   /** Jumps to `value`, cancelling any animation. */
   set(value: number) {
     this.stop();

package/src/web/ModalConfig.ts

@@ -9,6 +9,11 @@ import type {
 /** Snapshot of the props that shape a presentation. */
 export interface ModalConfig {
   mode: ModalMode;
+  /**
+   * A `bottomSheet` rendered in place, filling the host view: no backdrop,
+   * the page behind stays interactive, and the user can't dismiss it.
+   */
+  isInline: boolean;
   detents: SheetDetent[];
   initialDetentIndex: number;
   /** 0xAARRGGBB, from `processColor`. */
@@ -25,11 +30,19 @@ export interface ModalConfig {
   contentBackgroundColor: number | null;
   keyboardBehavior: KeyboardBehavior;
   popupAnimation: PopupAnimation;
+  pullToRefreshEnabled: boolean;
+  /** A refresh is in progress; `null` shows no refresh indicator. */
+  refreshing: boolean | null;
+  /** 0xAARRGGBB; `null` uses the default. */
+  refreshIndicatorColor: number | null;
 }
 
 export function makeConfig(props: NitroModalProps): ModalConfig {
+  // An inline sheet is part of the page; the user can't dismiss it.
+  const isInline = props.isInline && props.mode === 'bottomSheet';
   return {
     mode: props.mode,
+    isInline,
     detents: props.detents,
     initialDetentIndex: Number.isFinite(props.initialDetentIndex)
       ? Math.trunc(props.initialDetentIndex)
@@ -37,14 +50,17 @@ export function makeConfig(props: NitroModalProps): ModalConfig {
     backdropColor: props.backdropColor,
     backdropOpacity: props.backdropOpacity,
     backdropBlurRadius: props.backdropBlurRadius,
-    dismissOnBackdropPress: props.dismissOnBackdropPress,
-    dismissOnSwipe: props.dismissOnSwipe,
-    dismissOnBackButton: props.dismissOnBackButton,
+    dismissOnBackdropPress: props.dismissOnBackdropPress && !isInline,
+    dismissOnSwipe: props.dismissOnSwipe && !isInline,
+    dismissOnBackButton: props.dismissOnBackButton && !isInline,
     grabberVisible: props.grabberVisible,
     cornerRadius: props.cornerRadius >= 0 ? props.cornerRadius : null,
     contentBackgroundColor: props.contentBackgroundColor ?? null,
     keyboardBehavior: props.keyboardBehavior,
     popupAnimation: props.popupAnimation,
+    pullToRefreshEnabled: props.pullToRefreshEnabled,
+    refreshing: props.refreshing ?? null,
+    refreshIndicatorColor: props.refreshIndicatorColor ?? null,
   };
 }
 

package/src/web/ModalController.ts

@@ -6,7 +6,12 @@ import type {
   NitroModalMethods,
   NitroModalProps,
 } from '../NitroModal.nitro';
-import { canUseDOM, estimateViewport, readSafeAreaInsets } from './dom';
+import {
+  canUseDOM,
+  estimateViewport,
+  inlineInsets,
+  readSafeAreaInsets,
+} from './dom';
 import { isSameConfig, makeConfig, type ModalConfig } from './ModalConfig';
 import type {
   ModalElements,
@@ -58,6 +63,8 @@ export class ModalController implements PresenterListener {
   private isAttached = false;
   private presenter: ModalPresenter | null = null;
   private elements: ModalElements | null = null;
+  /** Inline: the element the sheet fills. */
+  private host: HTMLElement | null = null;
   private lastContentArea: ModalContentArea | null = null;
 
   /** `setMounted` renders (or removes) the modal's elements. */
@@ -110,6 +117,15 @@ export class ModalController implements PresenterListener {
     }
   }
 
+  /** Inline: the element the sheet fills, rendered in place. */
+  hostDidChange(host: HTMLElement | null) {
+    if (host === this.host) return;
+    this.host = host;
+    if (!this.presenter) {
+      this.reportEstimatedContentArea();
+    }
+  }
+
   elementsDidMount(elements: ModalElements) {
     this.elements = elements;
     if (this.presenter && !this.presenter.isShown) {
@@ -273,6 +289,10 @@ export class ModalController implements PresenterListener {
     this.props?.onDetentChange?.(index);
   }
 
+  onPullToRefresh() {
+    this.props?.onPullToRefresh?.();
+  }
+
   onContentAreaChange(width: number, height: number) {
     const area = { width: Math.floor(width), height: Math.floor(height) };
     const last = this.lastContentArea;
@@ -288,12 +308,25 @@ export class ModalController implements PresenterListener {
   private reportEstimatedContentArea() {
     const { config } = this;
     if (!canUseDOM || !this.isAttached || !config) return;
+    if (config.isInline) {
+      const { host } = this;
+      if (!host || host.clientWidth === 0 || host.clientHeight === 0) return;
+      const viewport = { width: host.clientWidth, height: host.clientHeight };
+      const area = sheetContentArea(
+        config.detents,
+        viewport,
+        inlineInsets(host),
+        true
+      );
+      this.onContentAreaChange(area.width, area.height);
+      return;
+    }
     const viewport = estimateViewport();
     const insets = readSafeAreaInsets();
     const area =
       config.mode === 'popup'
         ? popupContentArea(viewport, insets)
-        : sheetContentArea(config.detents, viewport, insets);
+        : sheetContentArea(config.detents, viewport, insets, false);
     this.onContentAreaChange(area.width, area.height);
   }