one 1.17.10 → 1.17.11

package/src/router/web/ScreenRenderContext.tsx

@@ -0,0 +1,61 @@
+'use client'
+
+import { createContext, useContext, type ComponentType, type ReactNode } from 'react'
+import type { NativeStackNavigationOptions } from '@react-navigation/native-stack'
+
+/**
+ * Props passed to a user-supplied screen-render component. Mirrors the
+ * native-stack option shape so the same render works for any overlay
+ * presentation (modal, formSheet, pageSheet, ...).
+ *
+ * `open` is driven by the router. The render component decides how to
+ * animate based on transitions of `open`, and calls `dismiss()` after its
+ * close animation completes (this triggers the actual `StackActions.pop`).
+ */
+export type StackRenderProps = {
+  routeKey: string
+  routeName: string
+  presentation: NonNullable<NativeStackNavigationOptions['presentation']>
+
+  /**
+   * Whether this overlay should currently be visible. For non-keepMounted
+   * routes, this is always `true` while the render is invoked. For
+   * keepMounted routes, this toggles as the user navigates away from /
+   * back to this route - the React subtree stays mounted in both states.
+   */
+  open: boolean
+
+  dismiss: () => void
+  dismissible: boolean
+
+  // sheet detent IR (pass-through from native-stack options)
+  sheetAllowedDetents?: number[] | 'fitToContents'
+  sheetGrabberVisible?: boolean
+  sheetCornerRadius?: number
+  sheetInitialDetentIndex?: number | 'last'
+  sheetLargestUndimmedDetentIndex?: number | 'none' | 'last'
+  sheetExpandsWhenScrolledToEdge?: boolean
+
+  children: ReactNode
+}
+
+export type StackRenderComponent = ComponentType<StackRenderProps>
+
+/**
+ * Platform-keyed render map. v1 consumes `web` only; `ios`/`android` are
+ * reserved for future use (a route overrides react-native-screens' native
+ * sheet with a custom impl).
+ */
+export type StackRender = {
+  web?: StackRenderComponent
+  ios?: StackRenderComponent
+  android?: StackRenderComponent
+}
+
+const StackRenderContext = createContext<StackRender | undefined>(undefined)
+
+export const StackRenderProvider = StackRenderContext.Provider
+
+export function useStackRender(): StackRender | undefined {
+  return useContext(StackRenderContext)
+}

package/src/router/web/WebStackNavigator.tsx

@@ -0,0 +1,87 @@
+'use client'
+
+import {
+  createNavigatorFactory,
+  StackActions,
+  StackRouter,
+  useNavigationBuilder,
+  type EventArg,
+  type ParamListBase,
+  type StackActionHelpers,
+  type StackNavigationState,
+  type StackRouterOptions,
+} from '@react-navigation/native'
+import type {
+  NativeStackNavigationEventMap,
+  NativeStackNavigationOptions,
+} from '@react-navigation/native-stack'
+import { useEffect, type ReactNode } from 'react'
+
+import { WebStackView } from './WebStackView'
+
+type WebStackNavigatorProps = {
+  initialRouteName?: string
+  screenOptions?: NativeStackNavigationOptions
+  children: ReactNode
+  id?: string
+  // accept anything else NativeStackNavigator does so withLayoutContext can pass through
+  [k: string]: any
+}
+
+/**
+ * Drop-in replacement for NativeStackNavigator on web.
+ *
+ * Uses the same router (StackRouter) and option shape as native-stack so
+ * navigation behavior is identical; the difference is that overlay-type
+ * presentations (modal, formSheet, ...) get peeled off the underlying view
+ * and rendered via the configured Stack render component in WebStackView.
+ */
+function WebStackNavigator({
+  initialRouteName,
+  children,
+  screenOptions,
+  ...rest
+}: WebStackNavigatorProps) {
+  const { state, navigation, descriptors, NavigationContent, describe } =
+    useNavigationBuilder<
+      StackNavigationState<ParamListBase>,
+      StackRouterOptions,
+      StackActionHelpers<ParamListBase>,
+      NativeStackNavigationOptions,
+      NativeStackNavigationEventMap
+    >(StackRouter, {
+      ...(rest as any),
+      children,
+      screenOptions,
+      initialRouteName,
+    })
+
+  // Mirror native-stack tabPress popToTop behavior
+  useEffect(() => {
+    // @ts-expect-error: tabPress may not exist on this navigation
+    return navigation?.addListener?.('tabPress', (e: EventArg<'tabPress', true>) => {
+      const isFocused = navigation.isFocused()
+      requestAnimationFrame(() => {
+        if (state.index > 0 && isFocused && !e.defaultPrevented) {
+          navigation.dispatch({
+            ...StackActions.popToTop(),
+            target: state.key,
+          })
+        }
+      })
+    })
+  }, [navigation, state.index, state.key])
+
+  return (
+    <NavigationContent>
+      <WebStackView
+        state={state}
+        navigation={navigation as any}
+        descriptors={descriptors as any}
+        describe={describe as any}
+      />
+    </NavigationContent>
+  )
+}
+
+export const createWebStackNavigator = createNavigatorFactory(WebStackNavigator)

package/src/router/web/WebStackView.tsx

@@ -0,0 +1,264 @@
+'use client'
+
+import {
+  StackActions,
+  type ParamListBase,
+  type StackActionHelpers,
+  type StackNavigationState,
+} from '@react-navigation/native'
+import type {
+  NativeStackNavigationEventMap,
+  NativeStackNavigationOptions,
+} from '@react-navigation/native-stack'
+import { NativeStackView } from '@react-navigation/native-stack'
+import {
+  Fragment,
+  useCallback,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+
+import {
+  convertStackStateToNonOverlayState,
+  findLastNonOverlayIndex,
+  isOverlayPresentation,
+} from './stackStateUtils'
+import {
+  type StackRender,
+  type StackRenderComponent,
+  type StackRenderProps,
+  useStackRender,
+} from './ScreenRenderContext'
+
+type RouteOptions = NativeStackNavigationOptions & {
+  render?: StackRender
+  keepMounted?: boolean
+}
+
+type Descriptors = Record<
+  string,
+  {
+    options: RouteOptions
+    render: () => ReactNode
+    navigation: any
+  }
+>
+
+type WebStackViewProps = {
+  state: StackNavigationState<ParamListBase>
+  navigation: StackActionHelpers<ParamListBase> & {
+    dispatch: (action: any) => void
+  }
+  descriptors: Descriptors
+  describe?: (route: any, placeholder?: boolean) => any
+  eventMap?: NativeStackNavigationEventMap
+}
+
+/**
+ * Resolve which render component to use for an overlay route, in order:
+ *   1. options.render?.web        (per-route override)
+ *   2. context.web                (Stack-level default; also fed by setupRendering)
+ * Returns undefined when neither is set.
+ */
+export function resolveOverlayRender(
+  options: RouteOptions | undefined,
+  contextRender: StackRender | undefined
+): StackRenderComponent | undefined {
+  return options?.render?.web ?? contextRender?.web
+}
+
+type PersistentSlot = {
+  routeName: string
+  Render: StackRenderComponent
+  options: RouteOptions
+  content: ReactElement
+}
+
+export function WebStackView({
+  state,
+  navigation,
+  descriptors,
+  describe,
+}: WebStackViewProps) {
+  const contextRender = useStackRender()
+
+  // Persistent slots survive route pops for routes with `keepMounted: true`.
+  // Keyed by route NAME (not key) so re-navigation reuses the same mount.
+  const persistentSlotsRef = useRef<Map<string, PersistentSlot>>(new Map())
+
+  // Capture / refresh persistent slots from current descriptors.
+  for (const route of state.routes) {
+    const desc = descriptors[route.key]
+    if (!desc) continue
+    const { options } = desc
+    if (!options.keepMounted) continue
+    if (!isOverlayPresentation(options)) continue
+    const Render = resolveOverlayRender(options, contextRender)
+    if (!Render) continue
+    if (persistentSlotsRef.current.has(route.name)) continue
+    persistentSlotsRef.current.set(route.name, {
+      routeName: route.name,
+      Render,
+      options,
+      content: desc.render() as ReactElement,
+    })
+  }
+
+  // Compute which routes are currently focused as overlays (trailing).
+  const isOverlayCandidate = (options: NativeStackNavigationOptions | undefined | null) =>
+    isOverlayPresentation(options) &&
+    resolveOverlayRender(options ?? undefined, contextRender) !== undefined
+
+  const nonOverlay = convertStackStateToNonOverlayState(
+    state,
+    descriptors,
+    isOverlayCandidate
+  )
+  const underlyingState = {
+    ...state,
+    routes: nonOverlay.routes,
+    index: nonOverlay.index,
+  } as StackNavigationState<ParamListBase>
+
+  const lastNonOverlay = findLastNonOverlayIndex(state, descriptors, isOverlayCandidate)
+  const trailingOverlays = state.routes.slice(lastNonOverlay + 1)
+
+  // Track which route NAMES are currently focused as a trailing overlay, so
+  // persistent slots know whether to be open or just kept-mounted-hidden.
+  const focusedOverlayNames = new Set(trailingOverlays.map((r) => r.name))
+
+  // Trailing overlays that AREN'T keepMounted render in the regular slot.
+  const regularOverlays = trailingOverlays.filter(
+    (r) => !descriptors[r.key]?.options.keepMounted
+  )
+
+  return (
+    <Fragment>
+      <NativeStackView
+        state={underlyingState}
+        descriptors={descriptors as any}
+        navigation={navigation as any}
+        describe={describe as any}
+      />
+
+      {regularOverlays.map((route) => (
+        <OverlayHost
+          key={route.key}
+          route={route}
+          descriptor={descriptors[route.key]!}
+          contextRender={contextRender}
+          open
+          onDismiss={() =>
+            navigation.dispatch({
+              ...StackActions.pop(),
+              source: route.key,
+              target: state.key,
+            })
+          }
+        />
+      ))}
+
+      {/* Persistent slots - render once each, never unmount. `open` toggles
+          based on whether the route is the current trailing overlay. */}
+      {Array.from(persistentSlotsRef.current.values()).map((slot) => (
+        <PersistentOverlayHost
+          key={slot.routeName}
+          slot={slot}
+          open={focusedOverlayNames.has(slot.routeName)}
+          onDismiss={() => {
+            // Find the live route key for this name (if any) and pop it.
+            const live = state.routes.find((r) => r.name === slot.routeName)
+            if (live) {
+              navigation.dispatch({
+                ...StackActions.pop(),
+                source: live.key,
+                target: state.key,
+              })
+            }
+          }}
+        />
+      ))}
+    </Fragment>
+  )
+}
+
+export function OverlayHost({
+  route,
+  descriptor,
+  contextRender,
+  open,
+  onDismiss,
+}: {
+  route: { key: string; name: string }
+  descriptor: Descriptors[string]
+  contextRender: StackRender | undefined
+  open: boolean
+  onDismiss: () => void
+}) {
+  const dismiss = useStableCallback(onDismiss)
+
+  const options = descriptor.options
+  const Render = resolveOverlayRender(options, contextRender)
+  const content = descriptor.render()
+
+  if (!Render || !isOverlayPresentation(options)) {
+    return <Fragment>{content}</Fragment>
+  }
+
+  const renderProps: StackRenderProps = {
+    routeKey: route.key,
+    routeName: route.name,
+    presentation: options.presentation!,
+    open,
+    dismiss,
+    dismissible: options.gestureEnabled ?? true,
+    sheetAllowedDetents: options.sheetAllowedDetents,
+    sheetGrabberVisible: options.sheetGrabberVisible,
+    sheetCornerRadius: options.sheetCornerRadius,
+    sheetInitialDetentIndex: options.sheetInitialDetentIndex,
+    sheetLargestUndimmedDetentIndex: options.sheetLargestUndimmedDetentIndex,
+    sheetExpandsWhenScrolledToEdge: options.sheetExpandsWhenScrolledToEdge,
+    children: content,
+  }
+
+  return <Render {...renderProps} />
+}
+
+function PersistentOverlayHost({
+  slot,
+  open,
+  onDismiss,
+}: {
+  slot: PersistentSlot
+  open: boolean
+  onDismiss: () => void
+}) {
+  const dismiss = useStableCallback(onDismiss)
+  const { Render, options, content, routeName } = slot
+
+  const renderProps: StackRenderProps = {
+    routeKey: `__keepMounted:${routeName}`,
+    routeName,
+    presentation: options.presentation!,
+    open,
+    dismiss,
+    dismissible: options.gestureEnabled ?? true,
+    sheetAllowedDetents: options.sheetAllowedDetents,
+    sheetGrabberVisible: options.sheetGrabberVisible,
+    sheetCornerRadius: options.sheetCornerRadius,
+    sheetInitialDetentIndex: options.sheetInitialDetentIndex,
+    sheetLargestUndimmedDetentIndex: options.sheetLargestUndimmedDetentIndex,
+    sheetExpandsWhenScrolledToEdge: options.sheetExpandsWhenScrolledToEdge,
+    children: content,
+  }
+
+  return <Render {...renderProps} />
+}
+
+function useStableCallback<T extends (...args: any[]) => any>(fn: T): T {
+  const [ref] = useState(() => ({ current: fn }))
+  ref.current = fn
+  return useCallback(((...args: any[]) => ref.current(...args)) as T, [ref])
+}