react-native-nitro-modal 0.1.5 → 0.2.0

package/src/NitroModalView.web.tsx

@@ -0,0 +1,138 @@
+/// <reference lib="dom" />
+
+import {
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { Modal } from 'react-native';
+import type { ReactNativeView } from 'react-native-nitro-modules';
+import type { NitroModalMethods, NitroModalProps } from './NitroModal.nitro';
+import { ModalController } from './web/ModalController';
+
+interface WebNitroModalViewProps extends NitroModalProps {
+  hybridRef?: (instance: NitroModalMethods) => void;
+  children?: ReactNode;
+}
+
+/** The web view takes plain functions; only native host components need them wrapped. */
+export function callback<T>(func: T): T {
+  return func;
+}
+
+/**
+ * Web implementation of the hybrid view. The modal renders through React
+ * 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.
+ */
+function WebNitroModalView(props: WebNitroModalViewProps) {
+  const { hybridRef, children } = props;
+  const [mounted, setMounted] = useState(false);
+  const [controller] = useState(() => new ModalController(setMounted));
+  const overlay = useRef<HTMLDivElement>(null);
+  const backdrop = useRef<HTMLDivElement>(null);
+  const surface = useRef<HTMLDivElement>(null);
+  const content = useRef<HTMLDivElement>(null);
+  const grabber = useRef<HTMLDivElement>(null);
+
+  useLayoutEffect(() => {
+    controller.attach();
+    return () => controller.detach();
+  }, [controller]);
+
+  useLayoutEffect(() => {
+    hybridRef?.(controller.methods as NitroModalMethods);
+  }, [controller, hybridRef]);
+
+  useLayoutEffect(() => {
+    controller.update(props);
+  });
+
+  useLayoutEffect(() => {
+    if (!mounted) return undefined;
+    controller.elementsDidMount({
+      overlay: overlay.current!,
+      backdrop: backdrop.current!,
+      surface: surface.current!,
+      content: content.current!,
+      grabber: grabber.current!,
+    });
+    return () => controller.elementsWillUnmount();
+  }, [controller, mounted]);
+
+  useLayoutEffect(() => {
+    if (mounted) {
+      controller.contentDidRender();
+    }
+  });
+
+  if (!mounted) return null;
+
+  // Styles set here never change; the presenters write sizes, positions,
+  // colors and animated values straight to the elements.
+  return (
+    <Modal
+      visible
+      transparent
+      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>
+    </Modal>
+  );
+}
+
+const styles = {
+  overlay: {
+    position: 'fixed',
+    inset: 0,
+    outline: 'none',
+  },
+  backdrop: {
+    position: 'absolute',
+    inset: 0,
+    touchAction: 'none',
+  },
+  surface: {
+    position: 'absolute',
+    left: 0,
+    top: 0,
+    boxSizing: 'border-box',
+    willChange: 'transform',
+  },
+  // Pinned at the origin like the native content view; the React content is
+  // positioned and sized inside it by `NitroModal`.
+  content: {
+    position: 'absolute',
+    left: 0,
+    top: 0,
+  },
+  grabber: {
+    position: 'absolute',
+    top: 5,
+    left: '50%',
+    width: 36,
+    height: 5,
+    marginLeft: -18,
+    borderRadius: 2.5,
+    backgroundColor: 'rgba(127, 127, 127, 0.4)',
+    pointerEvents: 'none',
+  },
+} satisfies Record<string, CSSProperties>;
+
+export const NitroModalView = WebNitroModalView as unknown as ReactNativeView<
+  NitroModalProps,
+  NitroModalMethods
+>;

package/src/web/AnimatedValue.ts

@@ -0,0 +1,189 @@
+/// <reference lib="dom" />
+
+/** How an `AnimatedValue` moves to its target. */
+export type Motion =
+  | {
+      type: 'spring';
+      /** Period of the undamped spring, in seconds. Lower is snappier. */
+      response: number;
+      /** 1 settles without overshoot; lower values bounce. */
+      dampingRatio: number;
+    }
+  | {
+      type: 'timing';
+      /** In milliseconds. */
+      duration: number;
+      easing: (progress: number) => number;
+    };
+
+/** Jumps to the target at once. The completion still arrives on the next frame. */
+export const INSTANT: Motion = {
+  type: 'timing',
+  duration: 0,
+  easing: (t) => t,
+};
+
+export interface AnimateOptions {
+  /** Starting velocity in units per second. Defaults to the current velocity. */
+  velocity?: number;
+  /** Finish as soon as a spring reaches the target instead of when it settles. */
+  stopAtTarget?: boolean;
+  /** Runs once the target is reached, unless another animation or `set` takes over first. */
+  onEnd?: () => void;
+}
+
+interface Run {
+  target: number;
+  motion: Motion;
+  options: AnimateOptions;
+  from: number;
+  startTime: number;
+  /** Side of the target the value started on, for `stopAtTarget`. */
+  side: number;
+}
+
+/** Longest frame integrated at once, so a dropped frame can't throw the spring off. */
+const MAX_FRAME_SECONDS = 0.064;
+const SPRING_STEP_SECONDS = 0.004;
+
+/**
+ * A number animated on `requestAnimationFrame` that reports every frame
+ * through `onChange`. A new animation starts from the current value and
+ * velocity, so transitions can be turned around mid-flight.
+ */
+export class AnimatedValue {
+  private current: number;
+  private speed = 0;
+  private run: Run | null = null;
+  private frame: number | null = null;
+  private lastTime = 0;
+
+  /** `precision`: distance from the target at which a spring counts as settled. */
+  constructor(
+    value: number,
+    private readonly precision: number,
+    private readonly onChange: (value: number) => void
+  ) {
+    this.current = value;
+  }
+
+  get value(): number {
+    return this.current;
+  }
+
+  /** Jumps to `value`, cancelling any animation. */
+  set(value: number) {
+    this.stop();
+    this.current = value;
+    this.speed = 0;
+    this.onChange(value);
+  }
+
+  stop() {
+    this.run = null;
+    if (this.frame != null) {
+      cancelAnimationFrame(this.frame);
+      this.frame = null;
+    }
+  }
+
+  animateTo(target: number, motion: Motion, options: AnimateOptions = {}) {
+    if (options.velocity !== undefined) {
+      this.speed = options.velocity;
+    }
+    const now = performance.now();
+    this.run = {
+      target,
+      motion,
+      options,
+      from: this.current,
+      startTime: now,
+      side: Math.sign(this.current - target),
+    };
+    if (motion.type === 'timing' && motion.duration <= 0) {
+      this.current = target;
+      this.speed = 0;
+      this.onChange(target);
+    }
+    if (this.frame == null) {
+      this.lastTime = now;
+      this.frame = requestAnimationFrame(this.step);
+    }
+  }
+
+  private step = (time: number) => {
+    this.frame = null;
+    const run = this.run;
+    if (!run) return;
+    const dt = Math.min(
+      Math.max((time - this.lastTime) / 1000, 0),
+      MAX_FRAME_SECONDS
+    );
+    this.lastTime = time;
+
+    const done =
+      run.motion.type === 'timing'
+        ? this.stepTiming(run, run.motion, time, dt)
+        : this.stepSpring(run, run.motion, dt);
+    if (done) {
+      this.current = run.target;
+      this.speed = 0;
+      this.run = null;
+    }
+    this.onChange(this.current);
+    if (done) {
+      run.options.onEnd?.();
+    } else {
+      this.frame = requestAnimationFrame(this.step);
+    }
+  };
+
+  private stepTiming(
+    run: Run,
+    motion: Extract<Motion, { type: 'timing' }>,
+    time: number,
+    dt: number
+  ): boolean {
+    const progress =
+      motion.duration > 0
+        ? Math.min(Math.max((time - run.startTime) / motion.duration, 0), 1)
+        : 1;
+    const next = run.from + (run.target - run.from) * motion.easing(progress);
+    if (dt > 0) {
+      this.speed = (next - this.current) / dt;
+    }
+    this.current = next;
+    return progress >= 1;
+  }
+
+  private stepSpring(
+    run: Run,
+    motion: Extract<Motion, { type: 'spring' }>,
+    dt: number
+  ): boolean {
+    const omega = (2 * Math.PI) / motion.response;
+    const stiffness = omega * omega;
+    const damping = 2 * motion.dampingRatio * omega;
+    let offset = this.current - run.target;
+    let velocity = this.speed;
+    const steps = Math.ceil(dt / SPRING_STEP_SECONDS);
+    for (let i = 0; i < steps; i++) {
+      const h = dt / steps;
+      velocity += (-stiffness * offset - damping * velocity) * h;
+      offset += velocity * h;
+    }
+    this.current = run.target + offset;
+    this.speed = velocity;
+
+    if (
+      run.options.stopAtTarget &&
+      (run.side === 0 || Math.sign(offset) !== run.side)
+    ) {
+      return true;
+    }
+    return (
+      Math.abs(offset) < this.precision &&
+      Math.abs(velocity) < this.precision * 20
+    );
+  }
+}

package/src/web/ModalConfig.ts

@@ -0,0 +1,57 @@
+import type {
+  KeyboardBehavior,
+  ModalMode,
+  NitroModalProps,
+  PopupAnimation,
+  SheetDetent,
+} from '../NitroModal.nitro';
+
+/** Snapshot of the props that shape a presentation. */
+export interface ModalConfig {
+  mode: ModalMode;
+  detents: SheetDetent[];
+  initialDetentIndex: number;
+  /** 0xAARRGGBB, from `processColor`. */
+  backdropColor: number;
+  backdropOpacity: number;
+  backdropBlurRadius: number;
+  dismissOnBackdropPress: boolean;
+  dismissOnSwipe: boolean;
+  dismissOnBackButton: boolean;
+  grabberVisible: boolean;
+  /** `null` uses the default. */
+  cornerRadius: number | null;
+  /** 0xAARRGGBB; `null` uses the system background. */
+  contentBackgroundColor: number | null;
+  keyboardBehavior: KeyboardBehavior;
+  popupAnimation: PopupAnimation;
+}
+
+export function makeConfig(props: NitroModalProps): ModalConfig {
+  return {
+    mode: props.mode,
+    detents: props.detents,
+    initialDetentIndex: Number.isFinite(props.initialDetentIndex)
+      ? Math.trunc(props.initialDetentIndex)
+      : 0,
+    backdropColor: props.backdropColor,
+    backdropOpacity: props.backdropOpacity,
+    backdropBlurRadius: props.backdropBlurRadius,
+    dismissOnBackdropPress: props.dismissOnBackdropPress,
+    dismissOnSwipe: props.dismissOnSwipe,
+    dismissOnBackButton: props.dismissOnBackButton,
+    grabberVisible: props.grabberVisible,
+    cornerRadius: props.cornerRadius >= 0 ? props.cornerRadius : null,
+    contentBackgroundColor: props.contentBackgroundColor ?? null,
+    keyboardBehavior: props.keyboardBehavior,
+    popupAnimation: props.popupAnimation,
+  };
+}
+
+export function isSameConfig(a: ModalConfig, b: ModalConfig): boolean {
+  return (Object.keys(a) as (keyof ModalConfig)[]).every((key) =>
+    key === 'detents'
+      ? a.detents.join() === b.detents.join()
+      : a[key] === b[key]
+  );
+}

package/src/web/ModalController.ts

@@ -0,0 +1,305 @@
+/// <reference lib="dom" />
+
+import type {
+  DismissReason,
+  ModalContentArea,
+  NitroModalMethods,
+  NitroModalProps,
+} from '../NitroModal.nitro';
+import { canUseDOM, estimateViewport, readSafeAreaInsets } from './dom';
+import { isSameConfig, makeConfig, type ModalConfig } from './ModalConfig';
+import type {
+  ModalElements,
+  ModalPresenter,
+  PresenterListener,
+} from './ModalPresenter';
+import { popupContentArea, PopupPresenter } from './PopupPresenter';
+import { sheetContentArea, SheetPresenter } from './SheetPresenter';
+
+type Phase = 'idle' | 'presenting' | 'presented' | 'dismissing';
+
+/**
+ * The web counterpart of the native `HybridNitroModal`: receives the host
+ * view's props and drives one presenter per presentation.
+ *
+ * Presentation is a small state machine so that rapid `isOpen` toggles, user
+ * dismissals and unmounts always settle on a consistent state, and every
+ * accepted present request ends with exactly one `onDismiss`. Transitions are
+ * interrupted rather than queued: closing mid-enter turns the enter around,
+ * and opening mid-exit turns the exit around (that session carries on, so it
+ * gets no `onDismiss` and at most one `onPresent`).
+ */
+export class ModalController implements PresenterListener {
+  readonly methods: Pick<
+    NitroModalMethods,
+    'present' | 'dismiss' | 'snapToDetent'
+  > = {
+    present: () => this.requestPresent(),
+    dismiss: () => this.requestDismiss('programmatic'),
+    snapToDetent: (index: number) => {
+      if (Number.isFinite(index)) {
+        this.presenter?.snapToDetent(Math.trunc(index));
+      }
+    },
+  };
+
+  private props: NitroModalProps | null = null;
+  private config: ModalConfig | null = null;
+  private isOpen = false;
+  private phase: Phase = 'idle';
+  /** What React (or an imperative call) asked for. */
+  private wantsOpen = false;
+  /** A present request was accepted and its `onDismiss` is still owed. */
+  private sessionActive = false;
+  /** `onPresent` was sent for the current session. */
+  private presentSent = false;
+  private dismissReason: DismissReason = 'programmatic';
+  private reconcileScheduled = false;
+  private isAttached = false;
+  private presenter: ModalPresenter | null = null;
+  private elements: ModalElements | null = null;
+  private lastContentArea: ModalContentArea | null = null;
+
+  /** `setMounted` renders (or removes) the modal's elements. */
+  constructor(private readonly setMounted: (mounted: boolean) => void) {}
+
+  // Host view lifecycle
+
+  attach() {
+    this.isAttached = true;
+    window.addEventListener('resize', this.handleWindowResize);
+  }
+
+  /** The host view unmounted. Also runs for React's strict-mode remount, so `attach` must work again. */
+  detach() {
+    this.isAttached = false;
+    window.removeEventListener('resize', this.handleWindowResize);
+    this.presenter?.destroy();
+    this.presenter = null;
+    this.phase = 'idle';
+    this.wantsOpen = false;
+    this.sessionActive = false;
+    this.presentSent = false;
+    this.dismissReason = 'programmatic';
+    // Applied again from the props on the next `update`.
+    this.isOpen = false;
+    this.config = null;
+    this.lastContentArea = null;
+    this.setMounted(false);
+  }
+
+  /** The host view rendered with new props. */
+  update(props: NitroModalProps) {
+    this.props = props;
+    const next = makeConfig(props);
+    if (!this.config || !isSameConfig(next, this.config)) {
+      this.config = next;
+      if (this.presenter) {
+        this.presenter.update(next);
+      } else {
+        this.reportEstimatedContentArea();
+      }
+    }
+    if (props.isOpen !== this.isOpen) {
+      this.isOpen = props.isOpen;
+      if (props.isOpen) {
+        this.requestPresent();
+      } else {
+        this.requestDismiss('programmatic');
+      }
+    }
+  }
+
+  elementsDidMount(elements: ModalElements) {
+    this.elements = elements;
+    if (this.presenter && !this.presenter.isShown) {
+      this.presenter.show(elements);
+    }
+  }
+
+  elementsWillUnmount() {
+    this.elements = null;
+  }
+
+  contentDidRender() {
+    this.presenter?.contentDidRender();
+  }
+
+  /** Escape key, routed by React Native Web's `Modal` to the topmost modal. */
+  handleBackPress = () => {
+    // Already on its way out: the press is spent.
+    if (!this.isVisible) return;
+    this.props?.onBackButtonPress?.();
+    if (!this.config?.dismissOnBackButton) return;
+    this.requestDismiss('backButton');
+    this.reconcile();
+  };
+
+  // State machine
+
+  private get isVisible(): boolean {
+    return this.phase === 'presenting' || this.phase === 'presented';
+  }
+
+  private requestPresent() {
+    if (!this.isAttached) return;
+    this.wantsOpen = true;
+    this.sessionActive = true;
+    this.scheduleReconcile();
+  }
+
+  private requestDismiss(reason: DismissReason) {
+    if (this.wantsOpen) {
+      this.dismissReason = reason;
+    }
+    this.wantsOpen = false;
+    this.scheduleReconcile();
+  }
+
+  /** Coalesces the requests made in one task, e.g. an open and a close in the same handler. */
+  private scheduleReconcile() {
+    if (this.reconcileScheduled) return;
+    this.reconcileScheduled = true;
+    queueMicrotask(() => {
+      this.reconcileScheduled = false;
+      if (this.isAttached) {
+        this.reconcile();
+      }
+    });
+  }
+
+  private reconcile() {
+    switch (this.phase) {
+      case 'presenting':
+      case 'presented':
+        if (!this.wantsOpen) {
+          this.startDismiss();
+        }
+        break;
+      case 'dismissing':
+        if (this.wantsOpen && this.presenter?.cancelDismiss()) {
+          this.phase = 'presenting';
+          this.dismissReason = 'programmatic';
+        }
+        break;
+      case 'idle':
+        if (this.wantsOpen) {
+          this.startPresent();
+        } else if (this.sessionActive) {
+          this.endSession(); // Cancelled before anything appeared.
+        }
+        break;
+    }
+  }
+
+  private startPresent() {
+    const { config } = this;
+    if (!canUseDOM || !config) return;
+    const presenter =
+      config.mode === 'popup'
+        ? new PopupPresenter(config, this)
+        : new SheetPresenter(config, this);
+    this.presenter = presenter;
+    this.phase = 'presenting';
+    this.setMounted(true);
+    // Still mounted from a presentation that just ended.
+    if (this.elements) {
+      presenter.show(this.elements);
+    }
+  }
+
+  private startDismiss() {
+    const { presenter } = this;
+    if (!presenter?.isShown) {
+      // Its elements never mounted.
+      presenter?.destroy();
+      this.finishDismiss();
+      return;
+    }
+    this.phase = 'dismissing';
+    presenter.dismiss();
+  }
+
+  private finishDismiss() {
+    this.phase = 'idle';
+    this.presenter = null;
+    this.setMounted(false);
+    this.endSession();
+    this.reconcile();
+  }
+
+  private endSession() {
+    if (!this.sessionActive) return;
+    const reason = this.dismissReason;
+    this.dismissReason = 'programmatic';
+    this.presentSent = false;
+    // A present requested while we were dismissing starts a new session.
+    this.sessionActive = this.wantsOpen;
+    if (this.isAttached) {
+      this.props?.onDismiss?.(reason);
+    }
+  }
+
+  // PresenterListener
+
+  onPresented() {
+    if (this.phase !== 'presenting') return;
+    this.phase = 'presented';
+    if (!this.presentSent) {
+      this.presentSent = true;
+      this.props?.onPresent?.();
+    }
+    this.reconcile();
+  }
+
+  onDismissed() {
+    this.finishDismiss();
+  }
+
+  onBackdropPress() {
+    this.props?.onBackdropPress?.();
+    if (!this.config?.dismissOnBackdropPress || !this.isVisible) return;
+    this.requestDismiss('backdrop');
+    this.reconcile();
+  }
+
+  onSwipeDismiss() {
+    if (!this.config?.dismissOnSwipe || !this.isVisible) return;
+    this.requestDismiss('swipe');
+    this.reconcile();
+  }
+
+  onDetentChange(index: number) {
+    this.props?.onDetentChange?.(index);
+  }
+
+  onContentAreaChange(width: number, height: number) {
+    const area = { width: Math.floor(width), height: Math.floor(height) };
+    const last = this.lastContentArea;
+    if (area.width <= 0 || area.height <= 0) return;
+    if (last?.width === area.width && last.height === area.height) return;
+    this.lastContentArea = area;
+    this.props?.onContentAreaChange?.(area);
+  }
+
+  // Helpers
+
+  /** Lets React size the content before the first presentation. */
+  private reportEstimatedContentArea() {
+    const { config } = this;
+    if (!canUseDOM || !this.isAttached || !config) return;
+    const viewport = estimateViewport();
+    const insets = readSafeAreaInsets();
+    const area =
+      config.mode === 'popup'
+        ? popupContentArea(viewport, insets)
+        : sheetContentArea(config.detents, viewport, insets);
+    this.onContentAreaChange(area.width, area.height);
+  }
+
+  private handleWindowResize = () => {
+    if (!this.presenter) {
+      this.reportEstimatedContentArea();
+    }
+  };
+}