@onekeyfe/react-native-native-overlay 3.0.162-alpha.268

package/src/animation/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Physical spring, identical to Reanimated / Tamagui:
+ * mass * x'' + damping * x' + stiffness * x = 0.
+ * Springs with a damping ratio above 1 are valid and common (`quick`).
+ */
+export interface IOverlaySpring {
+  mass: number;
+  stiffness: number;
+  damping: number;
+  /** Clamp the value at the target instead of overshooting. */
+  overshootClamping?: boolean;
+}
+
+export type IOverlayCubicBezier = readonly [number, number, number, number];
+
+export interface IOverlayTiming {
+  durationMs: number;
+  easing: IOverlayCubicBezier;
+}
+
+export type IOverlayMotion =
+  | { type: 'spring'; spring: IOverlaySpring }
+  | { type: 'timing'; timing: IOverlayTiming };
+
+/** Named motion tokens; each platform maps them to its own curve. */
+export type IOverlayMotionPreset =
+  | 'quick'
+  | 'popoverQuick'
+  | 'smooth'
+  | 'fast'
+  | 'medium'
+  | 'slow'
+  | 'toastSlide'
+  | 'lockFade';
+
+export type IOverlayMotionInput = IOverlayMotionPreset | IOverlayMotion;
+
+export type IOverlayEdge = 'top' | 'bottom' | 'left' | 'right';
+
+export interface IOverlayTransition {
+  /** `none` shows / hides immediately; content may animate itself. */
+  type: 'none' | 'fade' | 'slide' | 'scale';
+  /** `slide`: the edge the overlay travels from (enter) or to (exit). */
+  edge?: IOverlayEdge;
+  /** `slide`: travel in points; defaults to off-screen. */
+  distance?: number;
+  /** `scale`: start (enter) or end (exit) scale. */
+  scale?: number;
+  /** `scale`: extra translate along Y in points, e.g. -20 for custom toasts. */
+  offsetY?: number;
+  /** Fade opacity alongside slide / scale. Defaults to true for scale. */
+  fade?: boolean;
+  /** `scale`: `anchor` scales from the resolved anchor placement. */
+  origin?: 'center' | 'anchor';
+  motion?: IOverlayMotionInput;
+}
+
+export interface IOverlayAnimation {
+  enter?: IOverlayTransition;
+  /** Defaults to the reverse of `enter`. */
+  exit?: IOverlayTransition;
+  /** Backdrop fade; runs on the same clock as the content by default. */
+  backdrop?: { motion?: IOverlayMotionInput };
+}
+
+export type IOverlayPresentation =
+  | 'sheet'
+  | 'center'
+  | 'fullscreen'
+  | 'toast'
+  | 'anchored';

package/src/index.ts

@@ -0,0 +1,55 @@
+export * from './types';
+export {
+  OVERLAY_LEVELS,
+  OVERLAY_LEVEL_ORDER,
+  OVERLAY_WEB_PAGE_Z_INDEX_BASE,
+  OVERLAY_WEB_Z_INDEX_BASE,
+  isBlockingLevel,
+} from './OverlayLevels';
+export { OverlayRequestError } from './OverlayErrors';
+export { OverlayStore, findStatusBarOwner, overlayStore } from './OverlayStore';
+export type {
+  IOverlayBackResolution,
+  IOverlayEntryHandlers,
+  IOverlayStoreOptions,
+} from './OverlayStore';
+export * from './animation/types';
+export {
+  NATIVE_MOTION_PRESETS,
+  WEB_MOTION_PRESETS,
+} from './animation/motionPresets';
+export { OVERLAY_MOTION_PRESETS } from './animation/platformMotionPresets';
+export {
+  DEFAULT_OVERLAY_ANIMATIONS,
+  resolveOverlayAnimation,
+} from './animation/resolveAnimation';
+export type {
+  IResolvedOverlayAnimation,
+  IResolvedOverlayTransition,
+} from './animation/resolveAnimation';
+export {
+  springDampingRatio,
+  springNaturalFrequency,
+  springProgressAt,
+  springSettleTimeMs,
+  springToAndroidSpringForce,
+  springToCssLinear,
+} from './animation/spring';
+export { OverlayView } from './OverlayView';
+export {
+  useEnclosingOverlayLevel,
+  useNestedOverlayLevel,
+} from './OverlayLevelContext';
+export type {
+  IOverlayBackdrop,
+  IOverlayRequestDismissReason,
+  IOverlaySheetOptions,
+  IOverlayViewProps,
+} from './OverlayViewTypes';
+export {
+  OverlayPageHostScope,
+  OverlayPageOwnerScope,
+  useOverlayPageScope,
+} from './OverlayPageScope';
+export type { IOverlayPageScope } from './OverlayPageScope';
+export { OverlayPageHost } from './OverlayPageHost';

package/src/types.ts

@@ -0,0 +1,79 @@
+export type IOverlayScope = 'global' | 'page';
+
+export type IOverlayLevel =
+  | 'modal'
+  | 'hardware'
+  | 'secure'
+  | 'toast'
+  | 'lock'
+  | 'debug';
+
+export type IOverlayStrategy = 'stack' | 'queue' | 'replace';
+
+export type IOverlayPhase = 'queued' | 'active' | 'closing';
+
+export type IOverlayDismissReason =
+  | 'programmatic'
+  | 'back'
+  | 'backdrop'
+  | 'pan'
+  | 'replaced'
+  | 'page-removed'
+  | 'system';
+
+/** `light`: light content for dark overlays; `dark`: dark content. */
+export type IOverlayStatusBarStyle = 'light' | 'dark';
+
+export interface IOverlayRequest {
+  /** Stable id; generated when omitted. Re-requesting an existing id is a no-op. */
+  id?: string;
+  scope?: IOverlayScope;
+  level?: IOverlayLevel;
+  strategy?: IOverlayStrategy;
+  /** Queue ordering only: higher runs first, ties keep request order. */
+  priority?: number;
+  /**
+   * `replace` only: entries in the same lane with this key are replaced.
+   * When omitted, the topmost active entry of the lane is replaced.
+   */
+  replaceKey?: string;
+  /** Required for `page` scope: the root-route host that renders the entry. */
+  hostKey?: string;
+  /** Required for `page` scope: the nearest page that owns the entry. */
+  ownerKey?: string;
+  /** Receives back / Escape. Defaults to true for blocking levels. */
+  dismissible?: boolean;
+  /** Blocks interaction with everything below. Defaults by level. */
+  blocking?: boolean;
+  /**
+   * Status bar content while this is the topmost styled overlay; unset
+   * leaves the status bar alone.
+   */
+  statusBarStyle?: IOverlayStatusBarStyle;
+}
+
+export interface IOverlayEntry {
+  id: string;
+  scope: IOverlayScope;
+  level: IOverlayLevel;
+  strategy: IOverlayStrategy;
+  priority: number;
+  replaceKey: string | undefined;
+  hostKey: string | undefined;
+  ownerKey: string | undefined;
+  dismissible: boolean;
+  blocking: boolean;
+  statusBarStyle: IOverlayStatusBarStyle | undefined;
+  phase: IOverlayPhase;
+  /** True while the owning page is covered or detached; page scope only. */
+  suspended: boolean;
+  dismissReason: IOverlayDismissReason | undefined;
+  /** Monotonic request order. */
+  seq: number;
+}
+
+export interface IOverlaySnapshot {
+  /** Every non-queued entry in bottom-to-top render order. */
+  entries: readonly IOverlayEntry[];
+  queued: readonly IOverlayEntry[];
+}

package/src/useOverlayController.ts

@@ -0,0 +1,199 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+
+import { OVERLAY_MOTION_PRESETS } from './animation/platformMotionPresets';
+import { resolveOverlayAnimation } from './animation/resolveAnimation';
+import { useOverlayPageScope } from './OverlayPageScope';
+import { findStatusBarOwner, overlayStore } from './OverlayStore';
+
+import type { IResolvedOverlayAnimation } from './animation/resolveAnimation';
+import type {
+  IOverlayRequestDismissReason,
+  IOverlayViewProps,
+} from './OverlayViewTypes';
+import type { IOverlayEntry } from './types';
+
+export interface IOverlayController {
+  entry: IOverlayEntry | undefined;
+  /** Render the content (entry is active or closing). */
+  mounted: boolean;
+  /**
+   * Ask the host to show the content. Page entries stay presented while
+   * suspended; the page host hides them instead (the owner may be frozen).
+   */
+  presented: boolean;
+  scope: 'global' | 'page';
+  /** This entry's `statusBarStyle` currently drives the status bar. */
+  ownsStatusBar: boolean;
+  hostKey: string | undefined;
+  ownerKey: string | undefined;
+  animation: IResolvedOverlayAnimation;
+  onHostPresented: () => void;
+  onHostDismissed: () => void;
+  onHostRequestDismiss: (reason: IOverlayRequestDismissReason) => void;
+}
+
+function useLatest<T>(value: T) {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+
+/**
+ * Bridges a declarative overlay to the shared `overlayStore`: requests an
+ * entry while `visible`, follows the store's phase, and finalizes the entry
+ * once the host reports the end of the exit animation.
+ */
+export function useOverlayController(
+  props: IOverlayViewProps
+): IOverlayController {
+  const {
+    visible,
+    level,
+    strategy,
+    priority,
+    replaceKey,
+    blocking,
+    dismissOnBackPress,
+    presentation = 'center',
+    animation,
+    statusBarStyle,
+  } = props;
+  const pageScope = useOverlayPageScope();
+  const hostKey = props.hostKey ?? pageScope.hostKey;
+  const ownerKey = props.ownerKey ?? pageScope.ownerKey;
+  // Without a host or owner there is nowhere to anchor a page overlay.
+  const scope =
+    props.scope === 'page' && hostKey && ownerKey ? 'page' : 'global';
+  const baseId = useId();
+  const cycleRef = useRef(0);
+  const [entryId, setEntryId] = useState<string | undefined>();
+  // Set when the store closed the entry (replace, back) while `visible` is
+  // still true, so the effect below does not immediately reopen it.
+  const closedByStoreRef = useRef(false);
+  const propsRef = useLatest(props);
+
+  const snapshot = useSyncExternalStore(
+    overlayStore.subscribe,
+    overlayStore.getSnapshot,
+    overlayStore.getSnapshot
+  );
+  const entry = useMemo(
+    () =>
+      entryId
+        ? snapshot.entries.find((e) => e.id === entryId) ??
+          snapshot.queued.find((e) => e.id === entryId)
+        : undefined,
+    [entryId, snapshot]
+  );
+
+  useEffect(() => {
+    if (!visible) {
+      closedByStoreRef.current = false;
+      if (entryId) {
+        overlayStore.dismiss(entryId, 'programmatic');
+      }
+      return;
+    }
+    if (entryId || closedByStoreRef.current) {
+      return;
+    }
+    cycleRef.current += 1;
+    const id = `overlay-view${baseId}${cycleRef.current}`;
+    overlayStore.request(
+      {
+        id,
+        scope,
+        hostKey,
+        ownerKey,
+        level,
+        strategy,
+        priority,
+        replaceKey,
+        blocking,
+        dismissible: dismissOnBackPress,
+        statusBarStyle,
+      },
+      {
+        onRemoved: (reason) => {
+          setEntryId((current) => (current === id ? undefined : current));
+          if (reason !== 'programmatic') {
+            closedByStoreRef.current = true;
+          }
+          propsRef.current.onClose?.(reason);
+        },
+      }
+    );
+    setEntryId(id);
+    // Level / strategy changes apply to the next open cycle only.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [visible, entryId]);
+
+  useEffect(
+    () => () => {
+      if (entryId) {
+        overlayStore.dismiss(entryId, 'system');
+        overlayStore.finalize(entryId);
+      }
+    },
+    [entryId]
+  );
+
+  const resolvedAnimation = useMemo(
+    () =>
+      resolveOverlayAnimation(presentation, animation, OVERLAY_MOTION_PRESETS),
+    [presentation, animation]
+  );
+
+  const onHostPresented = useCallback(() => {
+    propsRef.current.onPresented?.();
+  }, [propsRef]);
+
+  const onHostDismissed = useCallback(() => {
+    if (!entryId) {
+      return;
+    }
+    const phase = overlayStore.getEntry(entryId)?.phase;
+    if (phase === 'active') {
+      // Native closed it on its own, e.g. a lower sheet in the same level
+      // window was dismissed and UIKit took the ones above with it.
+      overlayStore.dismiss(entryId, 'system');
+    }
+    overlayStore.finalize(entryId);
+  }, [entryId]);
+
+  const onHostRequestDismiss = useCallback(
+    (reason: IOverlayRequestDismissReason) => {
+      const handler = propsRef.current.onRequestDismiss;
+      handler?.(reason);
+      if (entryId && (!handler || reason === 'pan')) {
+        overlayStore.dismiss(entryId, reason);
+      }
+    },
+    [entryId, propsRef]
+  );
+
+  return {
+    entry,
+    mounted: !!entry && entry.phase !== 'queued',
+    presented:
+      !!entry &&
+      entry.phase === 'active' &&
+      (scope === 'page' || !entry.suspended),
+    scope,
+    ownsStatusBar: !!entryId && findStatusBarOwner(snapshot)?.id === entryId,
+    hostKey: scope === 'page' ? hostKey : undefined,
+    ownerKey: scope === 'page' ? ownerKey : undefined,
+    animation: resolvedAnimation,
+    onHostPresented,
+    onHostDismissed,
+    onHostRequestDismiss,
+  };
+}

package/src/useSuspendedPageOwners.ts

@@ -0,0 +1,26 @@
+import { useMemo, useSyncExternalStore } from 'react';
+
+import { overlayStore } from './OverlayStore';
+
+/**
+ * Owners whose page overlays in `hostKey` must be hidden. The page host
+ * applies this natively: the owning page may be frozen (freezeOnBlur) and
+ * cannot re-render its own overlays.
+ */
+export function useSuspendedPageOwners(hostKey: string): string[] {
+  const snapshot = useSyncExternalStore(
+    overlayStore.subscribe,
+    overlayStore.getSnapshot,
+    overlayStore.getSnapshot
+  );
+  const joined = snapshot.entries
+    .filter((e) => e.scope === 'page' && e.hostKey === hostKey && e.suspended)
+    .map((e) => e.ownerKey ?? '')
+    .filter(Boolean)
+    .toSorted()
+    .join('\n');
+  return useMemo(
+    () => (joined ? [...new Set(joined.split('\n'))] : []),
+    [joined]
+  );
+}

package/src/web/animateTransition.ts

@@ -0,0 +1,137 @@
+import { springToCssLinear } from '../animation/spring';
+
+import type { IResolvedOverlayTransition } from '../animation/resolveAnimation';
+import type { IOverlayMotion } from '../animation/types';
+
+export interface IContentExtent {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+/** Union of the rendered children rects; the content wrapper is full-window. */
+export function measureContentExtent(container: HTMLElement): IContentExtent {
+  const rects = Array.from(container.children).map((child) =>
+    child.getBoundingClientRect()
+  );
+  if (rects.length === 0) {
+    return {
+      top: 0,
+      bottom: window.innerHeight,
+      left: 0,
+      right: window.innerWidth,
+    };
+  }
+  return {
+    top: Math.min(...rects.map((r) => r.top)),
+    bottom: Math.max(...rects.map((r) => r.bottom)),
+    left: Math.min(...rects.map((r) => r.left)),
+    right: Math.max(...rects.map((r) => r.right)),
+  };
+}
+
+function toTiming(motion: IOverlayMotion): {
+  duration: number;
+  easing: string;
+} {
+  if (motion.type === 'timing') {
+    const [x1, y1, x2, y2] = motion.timing.easing;
+    return {
+      duration: motion.timing.durationMs,
+      easing: `cubic-bezier(${x1}, ${y1}, ${x2}, ${y2})`,
+    };
+  }
+  const { durationMs, easing } = springToCssLinear(motion.spring);
+  return { duration: durationMs, easing };
+}
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof globalThis.matchMedia === 'function' &&
+    globalThis.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+/** The off-stage keyframe for a transition: where enter starts / exit ends. */
+function hiddenKeyframe(
+  transition: IResolvedOverlayTransition,
+  extent: IContentExtent
+): Keyframe {
+  const frame: Keyframe = {};
+  if (transition.fade || transition.type === 'fade') {
+    frame.opacity = 0;
+  }
+  if (transition.type === 'slide') {
+    const edge = transition.edge ?? 'bottom';
+    const distance =
+      transition.distance ??
+      {
+        top: extent.bottom,
+        bottom: window.innerHeight - extent.top,
+        left: extent.right,
+        right: window.innerWidth - extent.left,
+      }[edge];
+    frame.transform = {
+      top: `translate3d(0, ${-distance}px, 0)`,
+      bottom: `translate3d(0, ${distance}px, 0)`,
+      left: `translate3d(${-distance}px, 0, 0)`,
+      right: `translate3d(${distance}px, 0, 0)`,
+    }[edge];
+  } else if (transition.type === 'scale') {
+    frame.transform = `translate3d(0, ${transition.offsetY ?? 0}px, 0) scale(${
+      transition.scale ?? 0.95
+    })`;
+  }
+  return frame;
+}
+
+const VISIBLE_KEYFRAME: Keyframe = {
+  opacity: 1,
+  transform: 'translate3d(0, 0, 0) scale(1)',
+};
+
+/**
+ * Runs an enter (`direction: 'in'`) or exit transition on `element`. The
+ * slide distance and scale origin come from the children of `contentRoot`,
+ * because the content wrapper itself always fills the window.
+ */
+export function animateTransition(
+  element: HTMLElement,
+  contentRoot: HTMLElement,
+  transition: IResolvedOverlayTransition,
+  direction: 'in' | 'out'
+): Animation | undefined {
+  if (transition.type === 'none') {
+    return undefined;
+  }
+  const effective: IResolvedOverlayTransition = prefersReducedMotion()
+    ? { ...transition, type: 'fade', fade: true }
+    : transition;
+  const extent = measureContentExtent(contentRoot);
+  element.style.transformOrigin = `${(extent.left + extent.right) / 2}px ${
+    (extent.top + extent.bottom) / 2
+  }px`;
+  const hidden = hiddenKeyframe(effective, extent);
+  const visible: Keyframe = {};
+  Object.keys(hidden).forEach((key) => {
+    visible[key] = VISIBLE_KEYFRAME[key];
+  });
+  const keyframes = direction === 'in' ? [hidden, visible] : [visible, hidden];
+  return element.animate(keyframes, {
+    ...toTiming(effective.motion),
+    fill: 'forwards',
+  });
+}
+
+export function animateBackdrop(
+  element: HTMLElement,
+  motion: IOverlayMotion,
+  direction: 'in' | 'out'
+): Animation {
+  const keyframes =
+    direction === 'in'
+      ? [{ opacity: 0 }, { opacity: 1 }]
+      : [{ opacity: 1 }, { opacity: 0 }];
+  return element.animate(keyframes, { ...toTiming(motion), fill: 'forwards' });
+}