one 1.22.0 → 1.23.0

package/src/headless/keepMounted.tsx

@@ -0,0 +1,46 @@
+'use client'
+
+import { Activity, Fragment, useEffect, useState } from 'react'
+
+import type { ScreenEntry } from './types'
+
+/**
+ * Tabs and Drawer hold every route in navigation state from the start, so a
+ * `keepMounted` screen must only stay mounted once it has actually been
+ * focused. Matches react-navigation's lazy behavior on native.
+ */
+export function useVisitedScreens(focusedKey: string) {
+  const [visited, setVisited] = useState<string[]>(() => [focusedKey])
+
+  useEffect(() => {
+    setVisited((prev) => (prev.includes(focusedKey) ? prev : [...prev, focusedKey]))
+  }, [focusedKey])
+
+  return visited
+}
+
+export function renderKeptMountedScreens(screens: ScreenEntry[], visited: string[]) {
+  return (
+    <Fragment>
+      {screens.map((screen) => {
+        if (screen.isFocused) {
+          return screen.keepMounted ? (
+            <Activity key={screen.key} mode="visible">
+              {screen.element}
+            </Activity>
+          ) : (
+            <Fragment key={screen.key}>{screen.element}</Fragment>
+          )
+        }
+
+        if (!screen.keepMounted || !visited.includes(screen.key)) return null
+
+        return (
+          <Activity key={screen.key} mode="hidden">
+            {screen.element}
+          </Activity>
+        )
+      })}
+    </Fragment>
+  )
+}

package/src/headless/types.ts

@@ -0,0 +1,72 @@
+import type { ComponentType, ReactElement, ReactNode } from 'react'
+
+// shared contract for headless web navigators. see plans/headless-navigators.md
+
+export type ScreenEntry = {
+  key: string
+  name: string
+  params: Record<string, any>
+  href: string
+  isFocused: boolean
+  keepMounted: boolean
+  // compiled options: semantic keys plus opaque passthrough of preset keys
+  options: Record<string, any>
+  // lazy: rendering it mounts the route (descriptor.render underneath)
+  element: ReactElement
+}
+
+export type UseStackResult = {
+  screens: ScreenEntry[]
+  focused: ScreenEntry
+}
+
+export type UseTabsResult = {
+  screens: ScreenEntry[]
+  focused: ScreenEntry
+}
+
+export type UseDrawerResult = {
+  screens: ScreenEntry[]
+  focused: ScreenEntry
+  isOpen: boolean
+  open: () => void
+  close: () => void
+  toggle: () => void
+}
+
+// the subset of Stack.Screen options each presentation understands. these are a
+// narrowed view of ScreenEntry['options'], never a copy of it
+export type SheetPresentationOptions = {
+  sheetAllowedDetents?: number[] | 'fitToContents'
+  sheetGrabberVisible?: boolean
+  sheetCornerRadius?: number
+  sheetExpandsWhenScrolledToEdge?: boolean
+  gestureEnabled?: boolean
+  title?: string
+}
+
+export type ModalPresentationOptions = {
+  gestureEnabled?: boolean
+  title?: string
+}
+
+type PresentationProps<Options> = {
+  /** whether the presentation should be visible. toggles as you navigate */
+  open: boolean
+  /** call with false when your UI dismisses. pops the screen */
+  onOpenChange: (open: boolean) => void
+  /** the presentation options set on the screen, same vocabulary as native */
+  options: Options
+  /** the full screen entry: name, params, complete options */
+  screen: ScreenEntry
+  /** the screen's content */
+  children: ReactNode
+}
+
+export type SheetPresentationProps = PresentationProps<SheetPresentationOptions>
+export type ModalPresentationProps = PresentationProps<ModalPresentationOptions>
+
+export type WebPresentations = {
+  sheet?: ComponentType<SheetPresentationProps>
+  modal?: ComponentType<ModalPresentationProps>
+}

package/src/headless/useDrawer.tsx

@@ -0,0 +1,88 @@
+'use client'
+
+import {
+  DrawerActions,
+  type DrawerActionHelpers,
+  type DrawerNavigationState,
+  type ParamListBase,
+} from '@react-navigation/routers'
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type PropsWithChildren,
+  type ReactElement,
+} from 'react'
+
+import { getPathFromState } from '../fork/getPathFromState'
+import { getResolvedLinking } from '../router/linkingConfig'
+import type { UseDrawerResult } from './types'
+
+export type HeadlessDrawerDescriptors = Record<
+  string,
+  {
+    options: Record<string, any>
+    render: () => ReactElement
+  }
+>
+
+type HeadlessDrawerNavigation = DrawerActionHelpers<ParamListBase> & {
+  dispatch: (action: any) => void
+}
+
+type DrawerStateProviderProps = PropsWithChildren<{
+  state: DrawerNavigationState<ParamListBase>
+  descriptors: HeadlessDrawerDescriptors
+  navigation: HeadlessDrawerNavigation
+}>
+
+const DrawerContext = createContext<UseDrawerResult | null>(null)
+
+export function DrawerStateProvider({
+  state,
+  descriptors,
+  navigation,
+  children,
+}: DrawerStateProviderProps) {
+  const linking = getResolvedLinking()
+  const value = useMemo<UseDrawerResult>(() => {
+    const screens = state.routes.map((route, index) => {
+      const descriptor = descriptors[route.key]!
+      const options = descriptor.options
+      const href = (linking?.getPathFromState ?? getPathFromState)(
+        { ...state, index },
+        linking?.config
+      )
+
+      return {
+        key: route.key,
+        name: route.name,
+        params: (route.params ?? {}) as Record<string, any>,
+        href,
+        isFocused: index === state.index,
+        keepMounted: options.keepMounted === true,
+        options,
+        element: descriptor.render(),
+      }
+    })
+
+    return {
+      screens,
+      focused: screens[state.index]!,
+      isOpen: state.history.some((entry) => entry.type === 'drawer'),
+      open: () => navigation.dispatch(DrawerActions.openDrawer()),
+      close: () => navigation.dispatch(DrawerActions.closeDrawer()),
+      toggle: () => navigation.dispatch(DrawerActions.toggleDrawer()),
+    }
+  }, [descriptors, linking, navigation, state])
+
+  return <DrawerContext.Provider value={value}>{children}</DrawerContext.Provider>
+}
+
+export function useDrawer(): UseDrawerResult {
+  const value = useContext(DrawerContext)
+  if (!value) {
+    throw new Error('useDrawer must be used inside a Drawer navigator')
+  }
+  return value
+}

package/src/headless/useStack.ts

@@ -0,0 +1,74 @@
+'use client'
+
+import type { ParamListBase } from '@react-navigation/core'
+import type { StackNavigationState } from '@react-navigation/routers'
+import {
+  createContext,
+  createElement,
+  useContext,
+  useMemo,
+  type PropsWithChildren,
+  type ReactElement,
+} from 'react'
+
+import type { UseStackResult } from './types'
+import { getPathFromState } from '../fork/getPathFromState'
+import { getResolvedLinking } from '../router/linkingConfig'
+
+export type HeadlessStackDescriptors = Record<
+  string,
+  {
+    options: Record<string, any>
+    render: () => ReactElement
+  }
+>
+
+type StackStateProviderProps = PropsWithChildren<{
+  state: StackNavigationState<ParamListBase>
+  descriptors: HeadlessStackDescriptors
+}>
+
+const StackContext = createContext<UseStackResult | null>(null)
+
+export function StackStateProvider({
+  state,
+  descriptors,
+  children,
+}: StackStateProviderProps) {
+  const linking = getResolvedLinking()
+  const value = useMemo<UseStackResult>(() => {
+    const screens = state.routes.map((route, index) => {
+      const descriptor = descriptors[route.key]!
+      const options = descriptor.options
+      const href = (linking?.getPathFromState ?? getPathFromState)(
+        { ...state, index },
+        linking?.config
+      )
+
+      return {
+        key: route.key,
+        name: route.name,
+        params: (route.params ?? {}) as Record<string, any>,
+        href,
+        isFocused: index === state.index,
+        keepMounted: options.keepMounted === true,
+        options,
+        element: descriptor.render(),
+      }
+    })
+
+    return { screens, focused: screens[state.index]! }
+  }, [descriptors, linking, state])
+
+  return createElement(StackContext.Provider, { value }, children)
+}
+
+export function useStack(): UseStackResult {
+  const value = useContext(StackContext)
+  if (!value) {
+    throw new Error(
+      'useStack() must be called inside a <Stack>. it is web-only: on native the stack is rendered by react-navigation.'
+    )
+  }
+  return value
+}

package/src/headless/useTabs.ts

@@ -0,0 +1,40 @@
+'use client'
+
+import { use, useMemo, type ReactElement } from 'react'
+
+import { appendBaseUrl } from '../fork/getPathFromState-mods'
+import { stripGroupSegmentsFromPath } from '../router/matchers'
+import { TabTriggerMapContext } from '../ui/TabContext'
+import { useNavigatorContext } from '../views/Navigator'
+import type { UseTabsResult } from './types'
+
+type TabsDescriptor = {
+  options: Record<string, any>
+  render: () => ReactElement
+}
+
+export function useTabs(): UseTabsResult {
+  const { state, descriptorsRef } = useNavigatorContext()
+  const triggerMap = use(TabTriggerMapContext)
+  const descriptors = descriptorsRef.current
+
+  return useMemo(() => {
+    const screens = state.routes.map((route, index) => {
+      const descriptor = descriptors[route.key] as TabsDescriptor
+      const config = triggerMap[route.name]
+
+      return {
+        key: route.key,
+        name: route.name,
+        params: (route.params ?? {}) as Record<string, any>,
+        href: config ? stripGroupSegmentsFromPath(appendBaseUrl(config.href)) : '',
+        isFocused: index === state.index,
+        keepMounted: descriptor.options.keepMounted === true,
+        options: descriptor.options,
+        element: descriptor.render(),
+      }
+    })
+
+    return { screens, focused: screens[state.index]! }
+  }, [descriptors, state, triggerMap])
+}

package/src/index.ts

@@ -81,6 +81,17 @@ export { href } from './href'
 export { getLinking, type OneLinkingConfig } from './link/getLinking'
 export { useSitemap, type SitemapType } from './router/sitemap'
 // components
+export { Presentations, type PresentationsProps } from './headless/Presentations'
+export { useStack } from './headless/useStack'
+export type {
+  ModalPresentationOptions,
+  ModalPresentationProps,
+  ScreenEntry,
+  SheetPresentationOptions,
+  SheetPresentationProps,
+  UseStackResult,
+  WebPresentations,
+} from './headless/types'
 export { Stack } from './layouts/Stack'
 export { Tabs } from './layouts/Tabs'
 export { Protected, type ProtectedProps } from './views/Protected'
@@ -95,24 +106,9 @@ export type {
   StackScreenOptions,
   StackScreenProps,
 } from './layouts/stack-utils'
-// Stack render API (for custom web overlay rendering)
-export type {
-  StackRender,
-  StackRenderComponent,
-  StackRenderProps,
-} from './router/web/ScreenRenderContext'
-// Tabs / Drawer render API + global setup
-export {
-  getRenderingConfig,
-  setupRendering,
-  type DrawerRender,
-  type DrawerRenderComponent,
-  type DrawerRenderProps,
-  type RenderingConfig,
-  type TabsRender,
-  type TabsRenderComponent,
-  type TabsRenderProps,
-} from './router/renderingRegistry'
+export { useTabs } from './headless/useTabs'
+export { useDrawer } from './headless/useDrawer'
+export type { UseTabsResult, UseDrawerResult } from './headless/types'
 // utilities
 export { withLayoutContext } from './layouts/withLayoutContext'
 export { Link } from './link/Link'

package/src/layouts/Drawer.tsx

@@ -4,10 +4,8 @@ import {
   type DrawerNavigationOptions,
 } from '@react-navigation/drawer'
 import type { DrawerNavigationState, ParamListBase } from '@react-navigation/native'
-import React, { useMemo, type ComponentProps } from 'react'
-import { Platform } from 'react-native'
+import React, { type ComponentProps } from 'react'
 
-import { getRenderingConfig, type DrawerRender } from '../router/renderingRegistry'
 import { withLayoutContext } from './withLayoutContext'
 
 const DrawerNavigator = createDrawerNavigator().Navigator
@@ -19,38 +17,9 @@ const RNDrawer = withLayoutContext<
   DrawerNavigationEventMap
 >(DrawerNavigator)
 
-type DrawerExtraProps = {
-  /**
-   * Platform-keyed sidebar component. Replaces the default drawer content.
-   * Dispatches on `Platform.OS` - `render.ios` works on iOS, `render.web`
-   * on web, etc. Falls back to `setupRendering({ Drawer: { ... } })` global
-   * if no prop is set, then to the built-in drawer content.
-   */
-  render?: DrawerRender
-}
-
-const DrawerWithRender = React.forwardRef<
-  unknown,
-  ComponentProps<typeof RNDrawer> & DrawerExtraProps
->((props, ref) => {
-  const { render, drawerContent, ...rest } = props as any
-
-  // Resolution: prop drawerContent > prop render[platform] > setupRendering[platform] > default
-  const effectiveDrawerContent = useMemo(() => {
-    if (drawerContent) return drawerContent
-    const platform = Platform.OS as 'web' | 'ios' | 'android'
-    const fromProp = render?.[platform]
-    if (fromProp) return fromProp
-    const fromGlobal = getRenderingConfig().Drawer?.[platform]
-    if (fromGlobal) return fromGlobal
-    return undefined
-  }, [drawerContent, render])
-
-  if (effectiveDrawerContent) {
-    return <RNDrawer {...rest} ref={ref} drawerContent={effectiveDrawerContent} />
-  }
-  return <RNDrawer {...rest} ref={ref} />
-})
+const DrawerWithRender = React.forwardRef<unknown, ComponentProps<typeof RNDrawer>>(
+  (props, ref) => <RNDrawer {...(props as any)} ref={ref} />
+)
 
 // Preserve withLayoutContext's static Screen so user code like
 // `<Drawer.Screen ... />` keeps working through the render wrapper.

package/src/layouts/Drawer.web.tsx

@@ -0,0 +1,117 @@
+'use client'
+
+import { createNavigatorFactory, useNavigationBuilder } from '@react-navigation/core'
+import type {
+  DrawerNavigationEventMap,
+  DrawerNavigationOptions,
+} from '@react-navigation/drawer'
+import {
+  type DrawerActionHelpers,
+  type DrawerNavigationState,
+  DrawerRouter,
+  type DrawerRouterOptions,
+  type ParamListBase,
+} from '@react-navigation/routers'
+import { Children, type ComponentProps, forwardRef, type ReactNode } from 'react'
+
+import { getCustomNavigatorChildren, isNavigatorConfigChild } from '../headless/children'
+import { devHeadlessNote } from '../headless/devHeadlessNote'
+import { renderKeptMountedScreens, useVisitedScreens } from '../headless/keepMounted'
+import {
+  DrawerStateProvider,
+  type HeadlessDrawerDescriptors,
+  useDrawer,
+} from '../headless/useDrawer'
+import { withLayoutContext } from './withLayoutContext'
+
+type WebDrawerNavigatorProps = {
+  children: ReactNode
+  headlessChildren?: ReactNode[]
+  initialRouteName?: string
+  defaultStatus?: DrawerRouterOptions['defaultStatus']
+  backBehavior?: DrawerRouterOptions['backBehavior']
+  screenOptions?: DrawerNavigationOptions | ((props: any) => DrawerNavigationOptions)
+  [key: string]: any
+}
+
+function WebDrawerNavigator({
+  children,
+  headlessChildren,
+  initialRouteName,
+  defaultStatus,
+  backBehavior,
+  screenOptions,
+  ...rest
+}: WebDrawerNavigatorProps) {
+  const { state, descriptors, navigation, NavigationContent } = useNavigationBuilder<
+    DrawerNavigationState<ParamListBase>,
+    DrawerRouterOptions,
+    DrawerActionHelpers<ParamListBase>,
+    DrawerNavigationOptions,
+    DrawerNavigationEventMap
+  >(DrawerRouter, {
+    ...(rest as any),
+    children,
+    initialRouteName,
+    defaultStatus,
+    backBehavior,
+    screenOptions,
+  })
+
+  return (
+    <NavigationContent>
+      <DrawerStateProvider
+        state={state}
+        descriptors={descriptors as HeadlessDrawerDescriptors}
+        navigation={navigation}
+      >
+        <HeadlessDrawerView customChildren={headlessChildren} />
+      </DrawerStateProvider>
+    </NavigationContent>
+  )
+}
+
+function HeadlessDrawerView({ customChildren }: { customChildren?: ReactNode[] }) {
+  const { screens, focused } = useDrawer()
+  const visited = useVisitedScreens(focused.key)
+
+  devHeadlessNote('Drawer')
+
+  if (customChildren?.length) {
+    return <>{customChildren}</>
+  }
+
+  return renderKeptMountedScreens(screens, visited)
+}
+
+const DrawerNavigator = createNavigatorFactory(WebDrawerNavigator)().Navigator
+
+const RNDrawer = withLayoutContext<
+  DrawerNavigationOptions,
+  typeof DrawerNavigator,
+  DrawerNavigationState<ParamListBase>,
+  DrawerNavigationEventMap
+>(DrawerNavigator)
+
+const DrawerWithHeadless = forwardRef<unknown, ComponentProps<typeof RNDrawer>>(
+  (props, ref) => {
+    const { children, ...rest } = props
+    const customChildren = getCustomNavigatorChildren(children)
+
+    return (
+      <RNDrawer
+        {...rest}
+        ref={ref}
+        headlessChildren={customChildren.length ? customChildren : undefined}
+      >
+        {Children.toArray(children).filter(isNavigatorConfigChild)}
+      </RNDrawer>
+    )
+  }
+)
+
+export const Drawer = Object.assign(DrawerWithHeadless, {
+  Screen: RNDrawer.Screen,
+})
+
+export default Drawer

package/src/layouts/Stack.tsx

@@ -1,25 +1,22 @@
 import type { ParamListBase, StackNavigationState } from '@react-navigation/native'
-import {
-  type NativeStackNavigationEventMap,
-  type NativeStackNavigationOptions,
+import type {
+  NativeStackNavigationEventMap,
+  NativeStackNavigationOptions,
 } from '@react-navigation/native-stack'
-import React, { Children, useMemo, type ComponentProps } from 'react'
-
+import React, { Children, type ComponentProps, useMemo } from 'react'
+import { isChildOfType } from '../utils/children'
+import { Protected } from '../views/Protected'
+import { Screen } from '../views/Screen'
+import { createStackNavigator, getStackNavigatorProps } from './stack-navigator'
 import {
-  StackScreen,
+  appendScreenStackPropsToOptions,
   StackHeader,
   StackHeaderComponent,
   StackHeaderSearchBar,
-  appendScreenStackPropsToOptions,
+  StackScreen,
   type StackScreenProps,
 } from './stack-utils'
 import { withLayoutContext } from './withLayoutContext'
-import { isChildOfType } from '../utils/children'
-import { Protected } from '../views/Protected'
-import { Screen } from '../views/Screen'
-import { createStackNavigator } from './stack-navigator'
-import { StackRenderProvider, type StackRender } from '../router/web/ScreenRenderContext'
-import { getRenderingConfig } from '../router/renderingRegistry'
 
 const NativeStackNavigator = createStackNavigator().Navigator
 
@@ -58,69 +55,64 @@ function mapChildren(children: React.ReactNode): React.ReactNode {
         return null
       }
 
-      // pass through other children (like Screen)
-      return child
+      if (isChildOfType(child, Screen)) {
+        return child
+      }
+
+      return null
     })
     .filter(Boolean)
 }
 
-type StackExtraProps = {
-  /**
-   * Platform-keyed render component for overlay routes (modal / formSheet /
-   * pageSheet / transparentModal / fullScreenModal). v1 consumes `web` only;
-   * `ios` / `android` are reserved for future use. Per-route overrides go on
-   * `<Stack.Screen options={{ render }} />`.
-   */
-  render?: StackRender
-}
-
 /**
  * Stack navigator with support for Header Composition API.
  * Wraps the base Stack to pre-process StackScreen children.
  */
-const StackWithComposition = React.forwardRef<
-  unknown,
-  ComponentProps<typeof RNStack> & StackExtraProps
->((props, ref) => {
-  const { children, screenOptions, render, ...rest } = props
-
-  // extract Stack.Header from children for screenOptions
-  const screenOptionsWithHeader = useMemo(() => {
-    const stackHeader = Children.toArray(children).find((child) =>
-      isChildOfType(child, StackHeaderComponent)
-    )
-
-    if (stackHeader && isChildOfType(stackHeader, StackHeaderComponent)) {
-      const headerProps: StackScreenProps = { children: stackHeader }
-      if (screenOptions) {
-        if (typeof screenOptions === 'function') {
-          return (...args: Parameters<typeof screenOptions>) => {
-            const opts = screenOptions(...args)
-            return appendScreenStackPropsToOptions(opts, headerProps)
+const StackWithComposition = React.forwardRef<unknown, ComponentProps<typeof RNStack>>(
+  (props, ref) => {
+    const { children, screenOptions, ...rest } = props
+
+    // extract Stack.Header from children for screenOptions
+    const screenOptionsWithHeader = useMemo(() => {
+      const stackHeader = Children.toArray(children).find((child) =>
+        isChildOfType(child, StackHeaderComponent)
+      )
+
+      if (stackHeader && isChildOfType(stackHeader, StackHeaderComponent)) {
+        const headerProps: StackScreenProps = { children: stackHeader }
+        if (screenOptions) {
+          if (typeof screenOptions === 'function') {
+            return (...args: Parameters<typeof screenOptions>) => {
+              const opts = screenOptions(...args)
+              return appendScreenStackPropsToOptions(opts, headerProps)
+            }
           }
+          return appendScreenStackPropsToOptions(screenOptions, headerProps)
         }
-        return appendScreenStackPropsToOptions(screenOptions, headerProps)
+        return appendScreenStackPropsToOptions({}, headerProps)
       }
-      return appendScreenStackPropsToOptions({}, headerProps)
-    }
-
-    return screenOptions
-  }, [children, screenOptions])
 
-  // pre-process children to convert StackScreen to Screen
-  const processedChildren = useMemo(() => mapChildren(children), [children])
+      return screenOptions
+    }, [children, screenOptions])
 
-  const navigator = (
-    <RNStack {...rest} ref={ref} screenOptions={screenOptionsWithHeader}>
-      {processedChildren}
-    </RNStack>
-  )
+    // pre-process children to convert StackScreen to Screen
+    const processedChildren = useMemo(() => mapChildren(children), [children])
+    const navigatorProps = useMemo(() => getStackNavigatorProps(children), [children])
 
-  // Per-instance prop wins; otherwise fall back to setupRendering global.
-  const effectiveRender = render ?? getRenderingConfig().Stack
-  if (!effectiveRender) return navigator
-  return <StackRenderProvider value={effectiveRender}>{navigator}</StackRenderProvider>
-})
+    return (
+      <RNStack
+        {...rest}
+        {...navigatorProps}
+        ref={ref}
+        screenOptions={
+          screenOptionsWithHeader as ComponentProps<typeof RNStack>['screenOptions']
+        }
+      >
+        {processedChildren}
+      </RNStack>
+    )
+  }
+)
 
 export const Stack = Object.assign(StackWithComposition, {
   Screen: StackScreen,