one 1.21.6 → 1.21.8

package/src/layouts/stack-utils/StackToolbar.types.ts

@@ -0,0 +1,98 @@
+import type { ReactNode } from 'react'
+import type { ColorValue, ImageSourcePropType, StyleProp, TextStyle } from 'react-native'
+
+export type StackToolbarPlacement = 'left' | 'right' | 'bottom'
+
+export interface StackToolbarProps {
+  children?: ReactNode
+  placement?: StackToolbarPlacement
+  asChild?: boolean
+  /** Android-only. One's Android toolbar host is not implemented yet. */
+  disableImePadding?: boolean
+  /** Android-only. One's Android toolbar host is not implemented yet. */
+  tintColor?: ColorValue
+  /** Android-only. One's Android toolbar host is not implemented yet. */
+  backgroundColor?: ColorValue
+}
+
+export interface StackToolbarIconProps {
+  src?: ImageSourcePropType
+  sf?: string
+  xcasset?: string
+  renderingMode?: 'template' | 'original'
+}
+
+export interface StackToolbarLabelProps {
+  children?: string
+}
+
+export interface StackToolbarBadgeProps {
+  children?: string
+  style?: StyleProp<
+    Pick<
+      TextStyle,
+      'fontFamily' | 'fontSize' | 'fontWeight' | 'color' | 'backgroundColor'
+    >
+  >
+}
+
+export interface StackToolbarItemProps {
+  children?: ReactNode
+  icon?: string | ImageSourcePropType
+  iconRenderingMode?: 'template' | 'original'
+  tintColor?: ColorValue
+  hidden?: boolean
+  disabled?: boolean
+  accessibilityLabel?: string
+  accessibilityHint?: string
+  hidesSharedBackground?: boolean
+  separateBackground?: boolean
+  style?: StyleProp<TextStyle>
+}
+
+export interface StackToolbarButtonProps extends StackToolbarItemProps {
+  image?: ImageSourcePropType
+  onPress?: () => void
+  selected?: boolean
+  variant?: 'plain' | 'done' | 'prominent'
+}
+
+export interface StackToolbarMenuProps extends StackToolbarItemProps {
+  image?: ImageSourcePropType
+  destructive?: boolean
+  title?: string
+  inline?: boolean
+  palette?: boolean
+  singleSelection?: boolean
+  elementSize?: 'auto' | 'small' | 'medium' | 'large'
+  variant?: 'plain' | 'done' | 'prominent'
+}
+
+export interface StackToolbarMenuActionProps extends StackToolbarItemProps {
+  image?: ImageSourcePropType
+  destructive?: boolean
+  discoverabilityLabel?: string
+  subtitle?: string
+  isOn?: boolean
+  onPress?: () => void
+  unstable_keepPresented?: boolean
+}
+
+export interface StackToolbarSpacerProps {
+  width?: number
+  hidden?: boolean
+  sharesBackground?: boolean
+}
+
+export interface StackToolbarSearchBarSlotProps {
+  hidden?: boolean
+  hidesSharedBackground?: boolean
+  separateBackground?: boolean
+}
+
+export interface StackToolbarViewProps {
+  children?: ReactNode
+  hidden?: boolean
+  hidesSharedBackground?: boolean
+  separateBackground?: boolean
+}

package/src/layouts/stack-utils/__tests__/StackToolbar.runtime.test.tsx

@@ -0,0 +1,46 @@
+import React from 'react'
+import TestRenderer, { act } from 'react-test-renderer'
+import { Platform } from 'react-native'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const setOptions = vi.fn()
+
+vi.mock('../../../router/useNavigation', () => ({
+  useNavigation: () => ({ setOptions }),
+}))
+
+import { StackToolbar } from '../StackToolbar'
+
+describe('StackToolbar runtime options', () => {
+  const originalOS = Platform.OS
+
+  afterEach(() => {
+    ;(Platform as any).OS = originalOS
+    setOptions.mockClear()
+  })
+
+  it('does not write undefined header overrides when the toolbar unmounts', () => {
+    ;(Platform as any).OS = 'ios'
+    let renderer: TestRenderer.ReactTestRenderer
+
+    act(() => {
+      renderer = TestRenderer.create(
+        <StackToolbar placement="right">
+          <StackToolbar.Button icon="bell" />
+        </StackToolbar>
+      )
+    })
+
+    expect(setOptions).toHaveBeenCalledTimes(1)
+    expect(setOptions).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        headerShown: true,
+        unstable_headerRightItems: expect.any(Function),
+      })
+    )
+
+    act(() => renderer!.unmount())
+
+    expect(setOptions).toHaveBeenCalledTimes(1)
+  })
+})

package/src/layouts/stack-utils/__tests__/composition.test.tsx

@@ -25,6 +25,7 @@ import {
 } from '../StackHeaderComponent'
 import { appendScreenStackPropsToOptions } from '../StackScreen'
 import { StackHeader } from '../index'
+import { StackToolbar, appendStackToolbarPropsToOptions } from '../StackToolbar'
 
 describe('Stack Header Composition', () => {
   describe('StackHeaderTitle', () => {
@@ -640,4 +641,179 @@ describe('Stack Header Composition', () => {
       })
     })
   })
+
+  describe('StackToolbar', () => {
+    const withIOS = <T,>(run: () => T): T => {
+      const originalOS = Platform.OS
+      ;(Platform as any).OS = 'ios'
+      try {
+        return run()
+      } finally {
+        ;(Platform as any).OS = originalOS
+      }
+    }
+
+    it('converts buttons, SF Symbols, badges, and iOS 26 background props to native header items', () =>
+      withIOS(() => {
+        const onPress = () => {}
+        const result = appendStackToolbarPropsToOptions(
+          { title: 'Inbox' },
+          {
+            placement: 'right',
+            children: (
+              <StackToolbar.Button
+                onPress={onPress}
+                selected
+                separateBackground
+                hidesSharedBackground
+              >
+                <StackToolbar.Icon sf="bell" />
+                <StackToolbar.Label>Notifications</StackToolbar.Label>
+                <StackToolbar.Badge style={{ color: 'white', backgroundColor: 'red' }}>
+                  5
+                </StackToolbar.Badge>
+              </StackToolbar.Button>
+            ),
+          }
+        )
+
+        expect(result.title).toBe('Inbox')
+        expect(result.headerShown).toBe(true)
+        const items = result.unstable_headerRightItems?.({} as any)
+        expect(items).toEqual([
+          expect.objectContaining({
+            type: 'button',
+            label: 'Notifications',
+            icon: { type: 'sfSymbol', name: 'bell' },
+            badge: {
+              value: '5',
+              style: expect.objectContaining({ color: 'white', backgroundColor: 'red' }),
+            },
+            selected: true,
+            sharesBackground: false,
+            hidesSharedBackground: true,
+            onPress,
+          }),
+        ])
+      }))
+
+    it('uses original image colors unless a tint or rendering mode requests a template', () =>
+      withIOS(() => {
+        const source = { uri: 'https://example.com/icon.png' }
+        const result = appendStackToolbarPropsToOptions(
+          {},
+          {
+            placement: 'right',
+            children: [
+              <StackToolbar.Button key="original" icon={source} />,
+              <StackToolbar.Button key="tinted" icon={source} tintColor="blue" />,
+              <StackToolbar.Button key="explicit" tintColor="blue">
+                <StackToolbar.Icon src={source} renderingMode="original" />
+              </StackToolbar.Button>,
+            ],
+          }
+        )
+
+        expect(result.unstable_headerRightItems?.({} as any)).toMatchObject([
+          { icon: { type: 'image', source, tinted: false } },
+          { icon: { type: 'image', source, tinted: true } },
+          { icon: { type: 'image', source, tinted: false } },
+        ])
+      }))
+
+    it('converts nested native menus and action state', () =>
+      withIOS(() => {
+        const archive = () => {}
+        const result = appendStackToolbarPropsToOptions(
+          {},
+          {
+            placement: 'left',
+            children: (
+              <StackToolbar.Menu title="Actions" icon="ellipsis.circle">
+                <StackToolbar.MenuAction icon="archivebox" isOn onPress={archive}>
+                  Archive
+                </StackToolbar.MenuAction>
+                <StackToolbar.Menu destructive inline title="Move to">
+                  <StackToolbar.MenuAction destructive>Trash</StackToolbar.MenuAction>
+                </StackToolbar.Menu>
+              </StackToolbar.Menu>
+            ),
+          }
+        )
+
+        const items = result.unstable_headerLeftItems?.({} as any)
+        expect(items).toHaveLength(1)
+        expect(items?.[0]).toMatchObject({
+          type: 'menu',
+          icon: { type: 'sfSymbol', name: 'ellipsis.circle' },
+          menu: {
+            title: 'Actions',
+            items: [
+              {
+                type: 'action',
+                label: 'Archive',
+                icon: { type: 'sfSymbol', name: 'archivebox' },
+                state: 'on',
+                onPress: archive,
+              },
+              {
+                type: 'submenu',
+                label: 'Move to',
+                inline: true,
+                destructive: true,
+                items: [{ type: 'action', label: 'Trash', destructive: true }],
+              },
+            ],
+          },
+        })
+      }))
+
+    it('merges left and right toolbars declared on Stack.Screen', () =>
+      withIOS(() => {
+        const result = appendScreenStackPropsToOptions(
+          { title: 'Document' },
+          {
+            children: [
+              <StackToolbar key="left" placement="left">
+                <StackToolbar.Button icon="sidebar.left" />
+              </StackToolbar>,
+              <StackToolbar key="right" placement="right">
+                <StackToolbar.Button icon="square.and.arrow.up" />
+              </StackToolbar>,
+            ],
+          }
+        )
+
+        expect(result.title).toBe('Document')
+        expect(result.unstable_headerLeftItems?.({} as any)).toHaveLength(1)
+        expect(result.unstable_headerRightItems?.({} as any)).toHaveLength(1)
+      }))
+
+    it('uses custom header content with asChild', () =>
+      withIOS(() => {
+        const custom = <button>Custom</button>
+        const result = appendStackToolbarPropsToOptions(
+          {},
+          { placement: 'right', asChild: true, children: custom }
+        )
+        expect(result.headerRight?.({} as any)).toBe(custom)
+        expect(result.unstable_headerRightItems).toBeUndefined()
+      }))
+
+    it('does not install native toolbar options on web', () => {
+      const originalOS = Platform.OS
+      ;(Platform as any).OS = 'web'
+      try {
+        const original = { title: 'Web' }
+        expect(
+          appendStackToolbarPropsToOptions(original, {
+            placement: 'right',
+            children: <StackToolbar.Button icon="star" />,
+          })
+        ).toBe(original)
+      } finally {
+        ;(Platform as any).OS = originalOS
+      }
+    })
+  })
 })

package/src/layouts/stack-utils/index.tsx

@@ -10,6 +10,7 @@ import {
   type StackHeaderSearchBarProps,
 } from './StackHeaderSearchBar'
 import { StackHeaderTitle, type StackHeaderTitleProps } from './StackHeaderTitle'
+import { StackToolbar } from './StackToolbar'
 
 /**
  * Compound component for configuring stack headers.
@@ -36,8 +37,23 @@ export {
   type StackHeaderSearchBarProps,
   StackHeaderTitle,
   type StackHeaderTitleProps,
+  StackToolbar,
 }
 
+export type {
+  StackToolbarBadgeProps,
+  StackToolbarButtonProps,
+  StackToolbarIconProps,
+  StackToolbarLabelProps,
+  StackToolbarMenuActionProps,
+  StackToolbarMenuProps,
+  StackToolbarPlacement,
+  StackToolbarProps,
+  StackToolbarSearchBarSlotProps,
+  StackToolbarSpacerProps,
+  StackToolbarViewProps,
+} from './StackToolbar'
+
 export {
   StackScreen,
   appendScreenStackPropsToOptions,

package/src/layouts/withLayoutContext.test.tsx

@@ -0,0 +1,74 @@
+import React from 'react'
+import TestRenderer, { act } from 'react-test-renderer'
+import { describe, expect, it } from 'vitest'
+import { Protected } from '../views/Protected'
+import { Screen } from '../views/Screen'
+import { useFilterScreenChildren } from './withLayoutContext'
+
+function readGuardedRedirects(children: React.ReactNode) {
+  let result: ReturnType<typeof useFilterScreenChildren> | undefined
+
+  function Capture() {
+    result = useFilterScreenChildren(children)
+    return null
+  }
+
+  act(() => {
+    TestRenderer.create(<Capture />)
+  })
+
+  return result!.guardedRedirects
+}
+
+describe('Protected redirectTo', () => {
+  it('associates a failed guard redirect with each protected screen', () => {
+    const redirects = readGuardedRedirects(
+      <Protected guard={false} redirectTo="/login">
+        <Screen name="dashboard" />
+        <Screen name="settings" />
+      </Protected>
+    )
+
+    expect(Array.from(redirects)).toEqual([
+      ['dashboard', '/login'],
+      ['settings', '/login'],
+    ])
+  })
+
+  it('uses the innermost failing guard redirect', () => {
+    const redirects = readGuardedRedirects(
+      <Protected guard={false} redirectTo="/login">
+        <Protected guard={false} redirectTo="/subscribe">
+          <Screen name="premium" />
+        </Protected>
+      </Protected>
+    )
+
+    expect(redirects.get('premium')).toBe('/subscribe')
+  })
+
+  it('inherits a failed parent redirect through a passing child guard', () => {
+    const redirects = readGuardedRedirects(
+      <Protected guard={false} redirectTo="/login">
+        <Protected guard>
+          <Screen name="account" />
+        </Protected>
+      </Protected>
+    )
+
+    expect(redirects.get('account')).toBe('/login')
+  })
+
+  it('ignores redirectTo on a passing parent guard', () => {
+    const redirects = readGuardedRedirects(
+      <Protected guard redirectTo="/login">
+        <Protected guard={false}>
+          <Screen name="account" />
+        </Protected>
+      </Protected>
+    )
+
+    expect(redirects.has('account')).toBe(true)
+    expect(redirects.get('account')).toBeUndefined()
+  })
+})

package/src/layouts/withLayoutContext.tsx

@@ -1,8 +1,17 @@
 import type { EventMapBase, NavigationState } from '@react-navigation/native'
 import React from 'react'
-import { useContextKey } from '../router/Route'
-import { registerProtectedRoutes, unregisterProtectedRoutes } from '../router/router'
+import type { OneRouter } from '../interfaces/router'
+import { getContextKey, stripInvisibleSegmentsFromPath } from '../router/matchers'
+import { useContextKey, useRouteNode } from '../router/Route'
+import {
+  registerProtectedRoutes,
+  replace,
+  resolveProtectedHref,
+  routeInfo,
+  unregisterProtectedRoutes,
+} from '../router/router'
 import { type ScreenProps, useSortedScreens } from '../router/useScreens'
+import { sortRoutesWithInitial } from '../router/sortRoutes'
 import type { PickPartial } from '../types'
 import { withStaticProperties } from '../utils/withStaticProperties'
 import { isProtectedElement } from '../views/Protected'
@@ -24,12 +33,17 @@ export function useFilterScreenChildren(
     const customChildren: any[] = []
     const screens: any[] = []
     const protectedScreens = new Set<string>()
+    const guardedRedirects = new Map<string, OneRouter.Href | undefined>()
 
     /**
      * Recursively process children, handling Protected elements.
      * When exclude is true, all Screen children are added to protectedScreens instead of screens.
      */
-    function flattenChild(child: React.ReactNode, exclude = false) {
+    function flattenChild(
+      child: React.ReactNode,
+      exclude = false,
+      redirectTo?: OneRouter.Href
+    ) {
       // Handle Screen or StackScreen elements
       if (
         React.isValidElement(child) &&
@@ -61,6 +75,7 @@ export function useFilterScreenChildren(
         const screenProps = child.props as ScreenProps
         if (exclude && screenProps.name) {
           protectedScreens.add(screenProps.name)
+          guardedRedirects.set(screenProps.name, redirectTo)
         } else {
           screens.push(screenProps)
         }
@@ -69,10 +84,11 @@ export function useFilterScreenChildren(
 
       // Handle Protected elements - recursively process children with guard logic
       if (isProtectedElement(child)) {
-        // Key logic: exclude if parent excluded OR guard is false
-        const excludeChildren = exclude || !child.props.guard
+        const guardFails = !child.props.guard
+        const excludeChildren = exclude || guardFails
+        const childRedirectTo = guardFails ? child.props.redirectTo : redirectTo
         React.Children.forEach(child.props.children, (nested) => {
-          flattenChild(nested, excludeChildren)
+          flattenChild(nested, excludeChildren, childRedirectTo)
         })
         return
       }
@@ -102,10 +118,40 @@ export function useFilterScreenChildren(
       screens,
       children: customChildren,
       protectedScreens,
+      guardedRedirects,
     }
   }, [children, contextKey, isCustomNavigator])
 }
 
+export function useResolvedGuardedRedirects(
+  guardedRedirects: Map<string, OneRouter.Href | undefined>
+) {
+  const node = useRouteNode()
+
+  return React.useMemo(() => {
+    if (!node) {
+      return guardedRedirects
+    }
+
+    const defaultRoute = [...node.children]
+      .sort(sortRoutesWithInitial(node.initialRouteName))
+      .find((child) => {
+        const normalized = child.route.replace(/\/index$/, '')
+        return !(guardedRedirects.has(child.route) || guardedRedirects.has(normalized))
+      })
+    const defaultHref = defaultRoute
+      ? stripInvisibleSegmentsFromPath(getContextKey(defaultRoute.contextKey)) || '/'
+      : undefined
+
+    return new Map(
+      Array.from(guardedRedirects, ([name, redirectTo]) => [
+        name,
+        redirectTo ?? defaultHref,
+      ])
+    )
+  }, [guardedRedirects, node])
+}
+
 /** Return a navigator that automatically injects matched routes and renders nothing when there are no children. Return type with children prop optional */
 export function withLayoutContext<
   TOptions extends object,
@@ -124,20 +170,33 @@ export function withLayoutContext<
       (propsIn, ref) => {
         const { children, ...props } = propsIn as React.ComponentProps<T>
         const contextKey = useContextKey()
-        const { screens, protectedScreens } = useFilterScreenChildren(children, {
-          contextKey,
-        })
+        const { screens, protectedScreens, guardedRedirects } = useFilterScreenChildren(
+          children,
+          { contextKey }
+        )
+        const resolvedGuardedRedirects = useResolvedGuardedRedirects(guardedRedirects)
 
         // Register protected routes globally so linkTo can block navigation to them
         // Register immediately (not just in effect) to catch navigation attempts during first render
-        registerProtectedRoutes(contextKey, protectedScreens)
+        registerProtectedRoutes(contextKey, resolvedGuardedRedirects)
+
+        const currentPathname = routeInfo?.pathname
+        const protectedHref = currentPathname
+          ? resolveProtectedHref(currentPathname)
+          : currentPathname
 
         React.useEffect(() => {
-          registerProtectedRoutes(contextKey, protectedScreens)
+          registerProtectedRoutes(contextKey, resolvedGuardedRedirects)
           return () => {
             unregisterProtectedRoutes(contextKey)
           }
-        }, [contextKey, protectedScreens])
+        }, [contextKey, resolvedGuardedRedirects])
+
+        React.useEffect(() => {
+          if (currentPathname && protectedHref && protectedHref !== currentPathname) {
+            replace(protectedHref)
+          }
+        }, [currentPathname, protectedHref])
 
         const processed = processor ? processor(screens ?? ([] as any)) : screens
         const sorted = useSortedScreens((processed ?? []) as any, {

package/src/router/Route.tsx

@@ -1,6 +1,7 @@
 import React, { createContext, type ReactNode, useContext } from 'react'
 import { findFocusedRoute } from '../fork/findFocusedRoute'
 import type { ErrorBoundaryProps } from '../views/Try'
+import type { SuspenseFallbackProps } from '../views/SuspenseFallback'
 import type { LoaderProps } from '../types'
 import type { One } from '../vite/types'
 import type { ParamValidator, RouteValidationFn } from '../validateParams'
@@ -37,6 +38,7 @@ export type SlotConfig = {
 
 export type LoadedRoute = {
   ErrorBoundary?: React.ComponentType<ErrorBoundaryProps>
+  SuspenseFallback?: React.ComponentType<SuspenseFallbackProps>
   default?: React.ComponentType<any>
   unstable_settings?: Record<string, any>
   getNavOptions?: (args: any) => any
@@ -124,8 +126,14 @@ export const RouteParamsContext = createContext<
 
 const CurrentRouteContext = React.createContext<RouteNode | null>(null)
 
+/** Allows a layout to provide a Suspense fallback for its child routes. */
+export const SuspenseFallbackContext = createContext<
+  React.ComponentType<SuspenseFallbackProps> | undefined
+>(undefined)
+
 if (process.env.NODE_ENV !== 'production') {
   CurrentRouteContext.displayName = 'RouteNode'
+  SuspenseFallbackContext.displayName = 'SuspenseFallback'
 }
 
 /** Return the RouteNode at the current contextual boundary. */

package/src/router/protectedRoutes.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  isRouteProtected,
+  registerProtectedRoutes,
+  resolveProtectedHref,
+  unregisterProtectedRoutes,
+} from './router'
+
+const contextKey = '/account'
+
+afterEach(() => {
+  unregisterProtectedRoutes(contextKey)
+})
+
+describe('protected route redirects', () => {
+  it('resolves a protected href to its redirect target', () => {
+    registerProtectedRoutes(contextKey, new Map([['settings', '/login']]))
+
+    expect(isRouteProtected('/account/settings?tab=billing')).toBe(true)
+    expect(resolveProtectedHref('/account/settings?tab=billing')).toBe('/login')
+  })
+
+  it('blocks a protected href without an explicit target', () => {
+    registerProtectedRoutes(contextKey, new Map([['settings', undefined]]))
+
+    expect(resolveProtectedHref('/account/settings')).toBeUndefined()
+  })
+
+  it('leaves allowed and similarly prefixed routes unchanged', () => {
+    registerProtectedRoutes(contextKey, new Map([['settings', '/login']]))
+
+    expect(resolveProtectedHref('/account/profile')).toBe('/account/profile')
+    expect(resolveProtectedHref('/accounting/settings')).toBe('/accounting/settings')
+  })
+})