react-native-theme-reveal 0.0.0-stage → 0.1.0

package/ios/ThemeRevealModule.swift

@@ -0,0 +1,264 @@
+import ExpoModulesCore
+import UIKit
+
+struct PointRecord: Record {
+  @Field var x: Double = 0
+  @Field var y: Double = 0
+}
+
+struct ShapeRecord: Record {
+  @Field var path: String = ""
+  @Field var anchor: PointRecord = PointRecord()
+  @Field var inscribedRadius: Double = 0
+}
+
+struct TransitionRecord: Record {
+  @Field var type: String = ""
+  @Field var durationMs: Double = 0
+  @Field var origin: PointRecord?
+  @Field var shape: ShapeRecord?
+  @Field var direction: String?
+}
+
+// Snapshot from capture(), kept out of the window until prepare() shows it. presented is the
+// window's top view controller at capture time, which a modal presented or dismissed since then
+// changes.
+private struct HeldCapture {
+  let view: UIView
+  weak var window: UIWindow?
+  weak var presented: UIViewController?
+  let takenAt: CFTimeInterval
+}
+
+public class ThemeRevealModule: Module {
+  private var overlay: RevealOverlay?
+  private var held: HeldCapture?
+  private var captureExpiry: DispatchWorkItem?
+  // Offset, in the overlay, of the React root a tapped view's origin is measured in (pageX /
+  // pageY). Read at snapshot time like on Android, so a modal that moves or closes before start
+  // doesn't shift the origin.
+  private var originOffset: CGPoint?
+  private var started: Promise?
+  // A snapshot that never gets start() would freeze the screen; drop it.
+  private var failsafe: DispatchWorkItem?
+
+  public func definition() -> ModuleDefinition {
+    Name("ThemeReveal")
+
+    // The capture path ("view": snapshotView), or nil when no overlay shows.
+    AsyncFunction("prepare") { (viewTag: Int?) -> String? in
+      self.prepare(viewTag)
+    }.runOnQueue(.main)
+
+    AsyncFunction("start") { (transition: TransitionRecord, promise: Promise) in
+      self.start(transition, promise)
+    }.runOnQueue(.main)
+
+    // prepare only snapshots the key window, so the view tag isn't needed here.
+    AsyncFunction("capture") { (_: Int?) -> Bool in
+      self.capture()
+    }.runOnQueue(.main)
+
+    AsyncFunction("dropCapture") {
+      self.dropCapture()
+    }.runOnQueue(.main)
+
+    AsyncFunction("cancel") {
+      self.dropCapture()
+      self.removeOverlay()
+    }.runOnQueue(.main)
+
+    // No-op on iOS: snapshotView(afterScreenUpdates:) keeps no thread or bitmap a warm-up could start early. It's
+    // here so the JS call resolves on both platforms.
+    AsyncFunction("warmUp") {}
+
+    OnAppEntersBackground {
+      Self.onMain { self.dropCapture() }
+    }
+
+    OnDestroy {
+      Self.onMain {
+        self.dropCapture()
+        self.removeOverlay()
+      }
+    }
+  }
+
+  private static func onMain(_ body: @escaping () -> Void) {
+    if Thread.isMainThread {
+      body()
+    } else {
+      DispatchQueue.main.async(execute: body)
+    }
+  }
+
+  // Takes the snapshot now and keeps it out of the window, so the screen stays live while
+  // the finger is down.
+  private func capture() -> Bool {
+    dropCapture()
+    let active = UIApplication.shared.applicationState == .active
+    // An overlay on screen would end up in the snapshot, so the switch snapshots after it instead.
+    guard overlay == nil,
+          Motion.canAnimate(active: active, reduceMotion: UIAccessibility.isReduceMotionEnabled),
+          let window = Self.keyWindow(),
+          let view = RevealOverlay.snapshot(of: window) else {
+      return false
+    }
+    held = HeldCapture(
+      view: view, window: window, presented: Self.topPresented(in: window), takenAt: CACurrentMediaTime())
+    let item = DispatchWorkItem { [weak self] in self?.dropCapture() }
+    captureExpiry = item
+    DispatchQueue.main.asyncAfter(deadline: .now() + Motion.captureTimeoutSeconds, execute: item)
+    return true
+  }
+
+  private func dropCapture() {
+    captureExpiry?.cancel()
+    captureExpiry = nil
+    held = nil
+  }
+
+  private func prepare(_ viewTag: Int?) -> String? {
+    removeOverlay()
+    let kept = held
+    dropCapture()
+    let active = UIApplication.shared.applicationState == .active
+    guard Motion.canAnimate(active: active, reduceMotion: UIAccessibility.isReduceMotionEnabled),
+          let window = Self.keyWindow(),
+          let next = Self.overlay(on: window, kept: kept) else {
+      return nil
+    }
+    overlay = next
+    originOffset = viewTag.flatMap { findView($0) }.flatMap(Self.reactRoot(of:)).flatMap { root in
+      root.window == nil ? nil : root.convert(CGPoint.zero, to: next.view)
+    }
+    let item = DispatchWorkItem { [weak self] in self?.removeOverlay() }
+    failsafe = item
+    DispatchQueue.main.asyncAfter(deadline: .now() + Self.failsafeSeconds, execute: item)
+    return "view"
+  }
+
+  private func start(_ transition: TransitionRecord, _ promise: Promise) {
+    guard let current = overlay else {
+      promise.resolve()
+      return
+    }
+    failsafe?.cancel()
+    failsafe = nil
+    started?.resolve()
+    started = promise
+    guard let window = current.view.window, let duration = Motion.durationSeconds(ms: transition.durationMs),
+          Motion.sameSize(current.size, window.bounds.size) else {
+      removeOverlay()
+      return
+    }
+    let onEnd = { [weak self, weak current] in
+      guard let self, let current, self.overlay === current else { return }
+      self.removeOverlay()
+    }
+    if !play(current, transition, duration, onEnd) {
+      removeOverlay()
+    }
+  }
+
+  private func play(
+    _ current: RevealOverlay, _ transition: TransitionRecord, _ duration: Double, _ onEnd: @escaping () -> Void
+  ) -> Bool {
+    switch transition.type {
+    case "reveal", "inverseReveal":
+      guard let origin = transition.origin, origin.x.isFinite, origin.y.isFinite else { return false }
+      let point = toOverlay(CGPoint(x: origin.x, y: origin.y), current)
+      current.reveal(
+        Self.shape(of: transition.shape), origin: point, inverse: transition.type == "inverseReveal",
+        duration: duration, onEnd: onEnd)
+    case "wipe":
+      guard let direction = transition.direction.flatMap(WipeDirection.init(rawValue:)) else { return false }
+      current.wipe(direction, duration: duration, onEnd: onEnd)
+    case "crossfade":
+      current.crossfade(duration: duration, onEnd: onEnd)
+    default:
+      return false
+    }
+    return true
+  }
+
+  private func removeOverlay() {
+    failsafe?.cancel()
+    failsafe = nil
+    let pending = started
+    started = nil
+    let current = overlay
+    overlay = nil
+    originOffset = nil
+    current?.remove()
+    pending?.resolve()
+  }
+
+  // Origin is relative to the tapped view's React root, or in window points if there's none.
+  private func toOverlay(_ point: CGPoint, _ current: RevealOverlay) -> CGPoint {
+    if let offset = originOffset {
+      return CGPoint(x: point.x + offset.x, y: point.y + offset.y)
+    }
+    return current.view.convert(point, from: nil)
+  }
+
+  // The held capture if it still shows this window at its size, otherwise a snapshot taken
+  // now.
+  private static func overlay(on window: UIWindow, kept: HeldCapture?) -> RevealOverlay? {
+    if let kept, Motion.canUseCapture(
+      sameWindow: kept.window === window, samePresentation: kept.presented === topPresented(in: window),
+      captured: kept.view.frame.size, current: window.bounds.size,
+      ageSeconds: CACurrentMediaTime() - kept.takenAt) {
+      return RevealOverlay(snapshot: kept.view, window: window)
+    }
+    return RevealOverlay(window: window)
+  }
+
+  // A React Native <Modal> presents a view controller in the same window.
+  private static func topPresented(in window: UIWindow) -> UIViewController? {
+    var top = window.rootViewController
+    while let next = top?.presentedViewController {
+      top = next
+    }
+    return top
+  }
+
+  private func findView(_ viewTag: Int) -> UIView? {
+    appContext?.findView(withTag: viewTag, ofType: UIView.self)
+  }
+
+  private static func keyWindow() -> UIWindow? {
+    UIApplication.shared.connectedScenes
+      .compactMap { $0 as? UIWindowScene }
+      .flatMap { $0.windows }
+      .first { $0.isKeyWindow }
+  }
+
+  // React Native measures pageX / pageY relative to the view its touch handler is attached
+  // to: the surface view, or a presented <Modal>'s view.
+  private static func reactRoot(of view: UIView) -> UIView? {
+    guard let handler: AnyClass = NSClassFromString("RCTSurfaceTouchHandler") else { return nil }
+    var candidate: UIView? = view
+    while let current = candidate {
+      if current.gestureRecognizers?.contains(where: { $0.isKind(of: handler) }) == true {
+        return current
+      }
+      candidate = current.superview
+    }
+    return nil
+  }
+
+  private static func shape(of record: ShapeRecord?) -> RevealShape {
+    guard let record else { return .circle }
+    guard let shape = RevealShape.parse(
+      path: record.path,
+      anchor: CGPoint(x: record.anchor.x, y: record.anchor.y),
+      inscribedRadius: CGFloat(record.inscribedRadius)) else {
+      log.warn("ThemeReveal: cannot parse the shape path \"\(record.path)\", using the circle")
+      return .circle
+    }
+    return shape
+  }
+
+  private static let failsafeSeconds = 1.0
+}

package/mocks/ThemeReveal.js

@@ -0,0 +1,10 @@
+// jest-expo loads this instead of the native module. prepare resolves null and capture false, so switchTo applies
+// the theme immediately without animating.
+module.exports = {
+  prepare: async () => null,
+  start: async () => {},
+  cancel: async () => {},
+  warmUp: async () => {},
+  capture: async () => false,
+  dropCapture: async () => {},
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "react-native-theme-reveal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Animate React Native theme switches from a native window snapshot",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "files": [
+    "build",
+    "android",
+    "ios",
+    "src",
+    "mocks",
+    "expo-module.config.json",
+    "!android/build",
+    "!android/.gradle",
+    "!android/.cxx",
+    "!android/src/test",
+    "!ios/build",
+    "!ios/Tests",
+    "!src/__tests__",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "expo-module test",
+    "prepare": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "theme",
+    "dark-mode",
+    "transition",
+    "animation"
+  ],
+  "repository": "https://github.com/chocky335/react-native-theme-reveal",
+  "bugs": {
+    "url": "https://github.com/chocky335/react-native-theme-reveal/issues"
+  },
+  "homepage": "https://github.com/chocky335/react-native-theme-reveal#readme",
+  "license": "MIT",
+  "devDependencies": {
+    "@testing-library/react-native": "^13.3.3",
+    "@types/react": "~19.2.10",
+    "babel-preset-expo": "~57.0.15",
+    "expo": "~57.0.29",
+    "expo-module-scripts": "^56.0.3",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "react-test-renderer": "19.2.3",
+    "typescript": "~5.9.2"
+  },
+  "peerDependencies": {
+    "expo": ">=57.0.0",
+    "react": "*",
+    "react-native": ">=0.86.0"
+  },
+  "overrides": {
+    "expo-module-scripts": {
+      "jest-expo": "~57.0.6",
+      "@react-native/jest-preset": "0.86.3"
+    }
+  }
+}

package/src/ThemeRevealModule.ts

@@ -0,0 +1,24 @@
+import { requireNativeModule } from 'expo'
+
+import type { CapturePath, Transition } from './types'
+
+type NativeThemeReveal = {
+  // The capture path, or null when no overlay shows.
+  prepare(viewTag: number | undefined): Promise<CapturePath | null>
+  start(transition: Transition): Promise<void>
+  cancel(): Promise<void>
+  warmUp(): Promise<void>
+  capture(viewTag: number | undefined): Promise<boolean>
+  dropCapture(): Promise<void>
+}
+
+const native = requireNativeModule<NativeThemeReveal>('ThemeReveal')
+
+export default {
+  prepare: (viewTag?: number): Promise<CapturePath | null> => native.prepare(viewTag),
+  start: (transition: Transition): Promise<void> => native.start(transition),
+  cancel: (): Promise<void> => native.cancel(),
+  warmUp: (): Promise<void> => native.warmUp(),
+  capture: (viewTag?: number): Promise<boolean> => native.capture(viewTag),
+  dropCapture: (): Promise<void> => native.dropCapture(),
+}

package/src/createThemeReveal.ts

@@ -0,0 +1,262 @@
+import { useEffect, useLayoutEffect } from 'react'
+import type { GestureResponderEvent } from 'react-native'
+
+import ThemeRevealModule from './ThemeRevealModule'
+import { pagePointOf } from './originFromPress'
+import { resolveTransition } from './resolveTransition'
+import { createStore, useStore } from './store'
+import type { CapturePath, Point, Shape, Transition, TransitionType, WipeDirection } from './types'
+
+export type SettledInfo = {
+  transition: TransitionType | null
+  // How the snapshot was taken, or null when there was none.
+  capture: CapturePath | null
+  prepareMs: number
+  totalMs: number
+}
+
+export type ThemeRevealOptions<T> = {
+  getTheme: () => T
+  setTheme: (theme: T) => void
+  shape?: Shape
+  durations?: Partial<Record<TransitionType, number>>
+  transition?: TransitionType
+  wipeDirection?: WipeDirection
+  onError?: (error: unknown) => void
+  onSettled?: (info: SettledInfo) => void
+  // Prepare the native snapshot path when useStart mounts (Android: the copy thread, then the GPU snapshot on API
+  // 29+, or one kept window-size bitmap below that). Default true.
+  warmUp?: boolean
+}
+
+export type SwitchOptions = {
+  transition?: TransitionType
+  shape?: Shape
+  wipeDirection?: WipeDirection
+}
+
+// Spread on a Pressable whose onPress calls switchTo. The snapshot is taken on press-in, and a press that ends
+// without a switch frees it.
+export type PressCapture = {
+  onPressIn(event: GestureResponderEvent): void
+  onPressOut(event?: GestureResponderEvent): void
+}
+
+export type ThemeReveal<T> = {
+  setOrigin(point: Point, viewTag?: number): void
+  capture(point: Point, viewTag?: number): void
+  dropCapture(): void
+  pressCapture: PressCapture
+  switchTo(theme: T, options?: SwitchOptions): Promise<void>
+  useStart(): void
+  useHeldTheme(): T | null
+}
+
+type PendingStart = {
+  id: number
+  transition: Transition
+  capture: CapturePath
+  startedAt: number
+  prepareMs: number
+}
+
+type Origin = { point: Point; viewTag?: number }
+
+type Captured = {
+  origin: Origin
+  expiry: ReturnType<typeof setTimeout>
+  drop?: ReturnType<typeof setTimeout>
+  // Touch time of the press-in, to tell this press's onPressOut apart from a late one from an earlier press.
+  pressedAt?: number
+  // Native freed the snapshot after the timeout. The origin stays until the press ends.
+  expired?: boolean
+}
+
+const timestampOf = (event: GestureResponderEvent | undefined): number | undefined => {
+  const { timestamp }: { timestamp?: unknown } = event?.nativeEvent ?? {}
+  return typeof timestamp === 'number' && Number.isFinite(timestamp) ? timestamp : undefined
+}
+
+// A capture no switch uses is freed after this long. Native also frees it on its own after the same time.
+const CAPTURE_TIMEOUT_MS = 3000
+
+type RevealState<T> = {
+  pending: PendingStart | null
+  held: { id: number; theme: T } | null
+}
+
+export function createThemeReveal<T>(options: ThemeRevealOptions<T>): ThemeReveal<T> {
+  const { getTheme, setTheme } = options
+  const warn = (error: unknown) => console.warn(error)
+  // A throwing user callback must not skip setTheme or leave an unhandled rejection.
+  const call = <A>(callback: ((arg: A) => void) | undefined, arg: A) => {
+    try {
+      callback?.(arg)
+    } catch (thrown) {
+      warn(thrown)
+    }
+  }
+  const onError = (error: unknown) => call(options.onError ?? warn, error)
+  const onSettled = (info: SettledInfo) => call(options.onSettled, info)
+  const store = createStore<RevealState<T>>({ pending: null, held: null })
+  let pendingOrigin: Origin | null = null
+  let captured: Captured | null = null
+  let latestId = 0
+  let warmedUp = false
+
+  const setOrigin = (point: Point, viewTag?: number) => {
+    pendingOrigin = { point, viewTag }
+  }
+
+  // Forgets the JS side of the capture and returns it. Native keeps it until prepare, cancel or dropCapture.
+  const releaseCapture = () => {
+    const current = captured
+    captured = null
+    if (current) {
+      clearTimeout(current.expiry)
+      clearTimeout(current.drop)
+    }
+    return current
+  }
+
+  const freeCapture = () => ThemeRevealModule.dropCapture().catch(onError)
+
+  const startCapture = (point: Point, viewTag: number | undefined, pressedAt: number | undefined) => {
+    releaseCapture()
+    const origin = { point, viewTag }
+    pendingOrigin = origin
+    // A long press keeps its point for the switch on release, but not the snapshot.
+    const current: Captured = {
+      origin,
+      pressedAt,
+      expiry: setTimeout(() => {
+        if (captured !== current) return
+        current.expired = true
+        freeCapture()
+      }, CAPTURE_TIMEOUT_MS),
+    }
+    captured = current
+    ThemeRevealModule.capture(viewTag).catch(onError)
+  }
+
+  const capture = (point: Point, viewTag?: number) => startCapture(point, viewTag, undefined)
+
+  const dropCapture = () => {
+    const current = releaseCapture()
+    if (current && pendingOrigin === current.origin) pendingOrigin = null
+    if (!current?.expired) freeCapture()
+  }
+
+  // On release React Native calls onPressOut before onPress in the same dispatch (or up to 130 ms after onPress
+  // for a short press), and a cancelled press gets onPressOut without onPress. So onPressOut only drops the
+  // capture in a later macrotask, and only if no switchTo has taken it by then. A late onPressOut whose touch is
+  // older than the capture's press-in belongs to an earlier press and leaves the capture alone.
+  const pressCapture: PressCapture = {
+    onPressIn: (event) => {
+      const origin = pagePointOf(event)
+      if (origin) startCapture(origin.point, origin.viewTag, timestampOf(event))
+    },
+    onPressOut: (event) => {
+      const current = captured
+      if (!current) return
+      const releasedAt = timestampOf(event)
+      if (current.pressedAt !== undefined && releasedAt !== undefined && releasedAt < current.pressedAt)
+        return
+      clearTimeout(current.drop)
+      current.drop = setTimeout(() => {
+        if (captured === current) dropCapture()
+      }, 0)
+    },
+  }
+
+  const switchTo = async (theme: T, switchOptions?: SwitchOptions) => {
+    const held = releaseCapture()
+    const origin = pendingOrigin
+    pendingOrigin = null
+    const id = ++latestId
+    const startedAt = performance.now()
+
+    if (Object.is(getTheme(), theme)) {
+      if (held && !held.expired) freeCapture()
+      try {
+        await ThemeRevealModule.cancel()
+      } catch (error) {
+        onError(error)
+      }
+      return
+    }
+
+    let capture: CapturePath | null = null
+    try {
+      capture = await ThemeRevealModule.prepare(origin?.viewTag)
+    } catch (error) {
+      onError(error)
+    }
+    if (id !== latestId) return
+    const prepareMs = performance.now() - startedAt
+
+    if (!capture) {
+      setTheme(theme)
+      onSettled({ transition: null, capture: null, prepareMs, totalMs: performance.now() - startedAt })
+      return
+    }
+
+    const transition = resolveTransition({
+      requested: switchOptions?.transition,
+      fallback: options.transition,
+      origin: origin?.point ?? null,
+      shape: options.shape,
+      durations: options.durations,
+      wipeDirection: options.wipeDirection,
+      requestedShape: switchOptions?.shape,
+      requestedWipeDirection: switchOptions?.wipeDirection,
+    })
+    store.set({ held: { id, theme: getTheme() } })
+    try {
+      setTheme(theme)
+    } catch (error) {
+      if (store.get().held?.id === id) store.set({ held: null })
+      ThemeRevealModule.cancel().catch(onError)
+      throw error
+    }
+    store.set({ pending: { id, transition, capture, startedAt, prepareMs } })
+  }
+
+  // Once per instance: start the native capture path early so the first switch doesn't pay for it.
+  const warmUp = () => {
+    if (warmedUp || options.warmUp === false) return
+    warmedUp = true
+    try {
+      ThemeRevealModule.warmUp().catch(onError)
+    } catch (error) {
+      onError(error)
+    }
+  }
+
+  const useStart = () => {
+    const pending = useStore(store, (state) => state.pending)
+
+    useEffect(warmUp, [])
+
+    useLayoutEffect(() => {
+      if (!pending || store.get().pending !== pending) return
+      store.set({ pending: null })
+      const { id, transition, capture, startedAt, prepareMs } = pending
+      ThemeRevealModule.start(transition)
+        .catch(onError)
+        .finally(() => {
+          if (store.get().held?.id === id) store.set({ held: null })
+          onSettled({
+            transition: transition.type,
+            capture,
+            prepareMs,
+            totalMs: performance.now() - startedAt,
+          })
+        })
+    }, [pending])
+  }
+
+  const useHeldTheme = () => useStore(store, (state) => state.held?.theme ?? null)
+
+  return { setOrigin, capture, dropCapture, pressCapture, switchTo, useStart, useHeldTheme }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { default as ThemeRevealModule } from './ThemeRevealModule'
+export { createThemeReveal } from './createThemeReveal'
+export { originFromPress } from './originFromPress'
+export type { MeasurableView, PressOrigin } from './originFromPress'
+export { resolveTransition } from './resolveTransition'
+export type { ResolveTransitionInput } from './resolveTransition'
+export type {
+  PressCapture,
+  SettledInfo,
+  SwitchOptions,
+  ThemeReveal,
+  ThemeRevealOptions,
+} from './createThemeReveal'
+export type { CapturePath, Point, Shape, Transition, TransitionType, WipeDirection } from './types'

package/src/originFromPress.ts

@@ -0,0 +1,40 @@
+import type { GestureResponderEvent } from 'react-native'
+
+import type { Point } from './types'
+
+export type MeasurableView = {
+  measureInWindow(callback: (x: number, y: number, width: number, height: number) => void): void
+}
+
+export type PressOrigin = { point: Point; viewTag?: number }
+
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value)
+
+const viewTagOf = (event: GestureResponderEvent): { viewTag?: number } => {
+  const { target }: { target?: unknown } = event.nativeEvent
+  return typeof target === 'number' ? { viewTag: target } : {}
+}
+
+// Touch point and target tag of a press event, or null when the event has no page point.
+export function pagePointOf(event: GestureResponderEvent): PressOrigin | null {
+  const { pageX, pageY }: { pageX?: unknown; pageY?: unknown } = event.nativeEvent
+  if (!isFiniteNumber(pageX) || !isFiniteNumber(pageY)) return null
+  return { point: { x: pageX, y: pageY }, ...viewTagOf(event) }
+}
+
+export function originFromPress(
+  event: GestureResponderEvent,
+  fallbackView?: MeasurableView | null,
+): Promise<PressOrigin | null> {
+  const tag = viewTagOf(event)
+  const origin = pagePointOf(event)
+
+  if (origin) return Promise.resolve(origin)
+  if (!fallbackView) return Promise.resolve(null)
+  return new Promise((resolve) => {
+    fallbackView.measureInWindow((x, y, width, height) => {
+      resolve({ point: { x: x + width / 2, y: y + height / 2 }, ...tag })
+    })
+  })
+}