one 1.2.69 → 1.2.71

package/src/fork/NavigationContainer.tsx

@@ -44,6 +44,7 @@ import { useThenable } from './useThenable'
 
 declare global {
   // eslint-disable-next-line no-var
+  // @ts-ignore - Type differs between react-navigation versions
   var REACT_NAVIGATION_DEVTOOLS: WeakMap<
     NavigationContainerRef<any>,
     { readonly linking: LinkingOptions<any> }
@@ -147,6 +148,7 @@ function NavigationContainerInner(
   // This will be used by the devtools
   React.useEffect(() => {
     if (refContainer.current) {
+      // @ts-ignore - Type differs between react-navigation versions in monorepo
       REACT_NAVIGATION_DEVTOOLS.set(refContainer.current, {
         get linking() {
           return {

package/src/index.ts

@@ -72,6 +72,16 @@ export { href } from './href'
 export { Stack } from './layouts/Stack'
 export { Tabs } from './layouts/Tabs'
 export { Protected, type ProtectedProps } from './views/Protected'
+// Stack header compositional API types
+export type {
+  StackHeaderProps,
+  StackHeaderBackButtonProps,
+  StackHeaderTitleProps,
+  StackHeaderLeftProps,
+  StackHeaderRightProps,
+  StackHeaderSearchBarProps,
+  StackScreenProps,
+} from './layouts/stack-utils'
 // utilities
 export { withLayoutContext } from './layouts/withLayoutContext'
 export { Link } from './link/Link'

package/src/layouts/Stack.tsx

@@ -4,16 +4,111 @@ import {
   type NativeStackNavigationEventMap,
   type NativeStackNavigationOptions,
 } from '@react-navigation/native-stack'
+import React, { Children, useMemo, type ComponentProps } from 'react'
 
+import {
+  StackScreen,
+  StackHeader,
+  StackHeaderComponent,
+  StackHeaderSearchBar,
+  appendScreenStackPropsToOptions,
+  type StackScreenProps,
+} from './stack-utils'
 import { withLayoutContext } from './withLayoutContext'
+import { isChildOfType } from '../utils/children'
+import { Protected } from '../views/Protected'
+import { Screen } from '../views/Screen'
 
 const NativeStackNavigator = createNativeStackNavigator().Navigator
 
-export const Stack = withLayoutContext<
+const RNStack = withLayoutContext<
   NativeStackNavigationOptions,
   typeof NativeStackNavigator,
   StackNavigationState<ParamListBase>,
   NativeStackNavigationEventMap
 >(NativeStackNavigator)
 
+/**
+ * Pre-process children to convert StackScreen (with Header children) to Screen (with options).
+ * This allows the Header Composition API to work in layout files.
+ */
+function mapChildren(children: React.ReactNode): React.ReactNode {
+  return Children.toArray(children)
+    .map((child, index) => {
+      if (isChildOfType(child, StackScreen)) {
+        // convert StackScreen to Screen with options extracted from Header children
+        const options = appendScreenStackPropsToOptions({}, child.props)
+        const { children: _, ...rest } = child.props
+        return <Screen key={child.props.name ?? index} {...rest} options={options} />
+      }
+
+      if (isChildOfType(child, Protected)) {
+        // recursively process Protected children
+        return (
+          <Protected key={`protected-${index}`} guard={child.props.guard}>
+            {mapChildren(child.props.children)}
+          </Protected>
+        )
+      }
+
+      if (isChildOfType(child, StackHeaderComponent)) {
+        // Stack.Header at the Stack level is used for screenOptions, handled separately
+        return null
+      }
+
+      // pass through other children (like Screen)
+      return child
+    })
+    .filter(Boolean)
+}
+
+/**
+ * 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>>(
+  (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({}, headerProps)
+      }
+
+      return screenOptions
+    }, [children, screenOptions])
+
+    // pre-process children to convert StackScreen to Screen
+    const processedChildren = useMemo(() => mapChildren(children), [children])
+
+    return (
+      <RNStack {...rest} ref={ref} screenOptions={screenOptionsWithHeader}>
+        {processedChildren}
+      </RNStack>
+    )
+  }
+)
+
+export const Stack = Object.assign(StackWithComposition, {
+  Screen: StackScreen,
+  Header: StackHeader,
+  Protected,
+  SearchBar: StackHeaderSearchBar,
+})
+
 export default Stack

package/src/layouts/stack-utils/README.md

@@ -0,0 +1,211 @@
+# Stack Header Composition API
+
+A declarative JSX API for configuring native stack headers in One.
+
+## Overview
+
+The Stack Header Composition API provides a more intuitive way to configure stack navigation headers using JSX components instead of the traditional options object. This is particularly useful for complex header configurations like large titles, custom buttons, and search bars.
+
+## Installation
+
+The components are available through the main `one` package:
+
+```tsx
+import { Stack } from 'one'
+```
+
+## Core Components
+
+| Component | Description |
+|-----------|-------------|
+| `Stack.Screen` | Screen wrapper with header composition support |
+| `Stack.Header` | Main header configuration container |
+| `Stack.Header.Title` | Configure title text and large title mode |
+| `Stack.Header.Left` | Custom left header content |
+| `Stack.Header.Right` | Custom right header content |
+| `Stack.Header.BackButton` | Back button configuration |
+| `Stack.Header.SearchBar` | Search bar configuration |
+
+## Basic Usage
+
+```tsx
+import { Stack } from 'one'
+
+export default function Layout() {
+  return (
+    <Stack>
+      <Stack.Screen name="index">
+        <Stack.Header>
+          <Stack.Header.Title large>Welcome</Stack.Header.Title>
+        </Stack.Header>
+      </Stack.Screen>
+    </Stack>
+  )
+}
+```
+
+## Large Title with Blur Effect (iOS)
+
+The classic iOS large title pattern with blur effect:
+
+```tsx
+<Stack.Screen name="feed">
+  <Stack.Header blurEffect="regular" style={{ backgroundColor: 'transparent' }}>
+    <Stack.Header.Title large>Feed</Stack.Header.Title>
+  </Stack.Header>
+</Stack.Screen>
+```
+
+## Custom Header Buttons
+
+Add custom buttons to the left or right side of the header:
+
+```tsx
+<Stack.Screen name="profile">
+  <Stack.Header>
+    <Stack.Header.Title>Profile</Stack.Header.Title>
+    <Stack.Header.Left asChild>
+      <Button onPress={goBack}>Back</Button>
+    </Stack.Header.Left>
+    <Stack.Header.Right asChild>
+      <Button onPress={openSettings}>Settings</Button>
+    </Stack.Header.Right>
+  </Stack.Header>
+</Stack.Screen>
+```
+
+## Search Bar
+
+Add an integrated search bar to the header:
+
+```tsx
+<Stack.Screen name="search">
+  <Stack.Header>
+    <Stack.Header.Title>Search</Stack.Header.Title>
+    <Stack.Header.SearchBar
+      placeholder="Search..."
+      onChangeText={handleSearch}
+    />
+  </Stack.Header>
+</Stack.Screen>
+```
+
+## Back Button Configuration
+
+Customize the back button appearance and behavior:
+
+```tsx
+<Stack.Screen name="detail">
+  <Stack.Header>
+    <Stack.Header.Title>Detail</Stack.Header.Title>
+    <Stack.Header.BackButton
+      displayMode="minimal"
+      hidden={false}
+    >
+      Back
+    </Stack.Header.BackButton>
+  </Stack.Header>
+</Stack.Screen>
+```
+
+## Custom Header Component
+
+Replace the entire header with a custom component:
+
+```tsx
+<Stack.Screen name="custom">
+  <Stack.Header asChild>
+    <CustomHeader />
+  </Stack.Header>
+</Stack.Screen>
+```
+
+## Combining with Options
+
+You can combine the composition API with the traditional options prop:
+
+```tsx
+<Stack.Screen
+  name="mixed"
+  options={{
+    animation: 'slide_from_right',
+    gestureEnabled: true,
+  }}
+>
+  <Stack.Header>
+    <Stack.Header.Title large>Mixed Config</Stack.Header.Title>
+  </Stack.Header>
+</Stack.Screen>
+```
+
+## API Reference
+
+### Stack.Header Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `hidden` | `boolean` | Hide the header entirely |
+| `asChild` | `boolean` | Render children as the entire header |
+| `blurEffect` | `'regular' \| 'prominent' \| ...` | iOS blur effect |
+| `style` | `StyleProp` | Header style (backgroundColor, shadowColor) |
+| `largeStyle` | `StyleProp` | Large title header style |
+
+### Stack.Header.Title Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `string` | Title text |
+| `large` | `boolean` | Enable large title mode |
+| `style` | `StyleProp` | Title text style |
+| `largeStyle` | `StyleProp` | Large title text style |
+
+### Stack.Header.Left / Right Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Content to render |
+| `asChild` | `boolean` | Required to render custom content |
+
+### Stack.Header.BackButton Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `string` | Back button title |
+| `hidden` | `boolean` | Hide the back button |
+| `displayMode` | `'default' \| 'minimal' \| 'generic'` | Display mode |
+| `withMenu` | `boolean` | Enable back button menu |
+| `src` | `ImageSourcePropType` | Custom back button image |
+| `style` | `TextStyle` | Back button title style |
+
+### Stack.Header.SearchBar Props
+
+Accepts all props from `react-native-screens` SearchBarProps.
+
+## Comparison with Options API
+
+**Traditional options API:**
+```tsx
+<Stack.Screen
+  name="index"
+  options={{
+    title: 'Welcome',
+    headerLargeTitle: true,
+    headerBlurEffect: 'regular',
+    headerRight: () => <Button>Action</Button>,
+  }}
+/>
+```
+
+**Composition API:**
+```tsx
+<Stack.Screen name="index">
+  <Stack.Header blurEffect="regular">
+    <Stack.Header.Title large>Welcome</Stack.Header.Title>
+    <Stack.Header.Right asChild>
+      <Button>Action</Button>
+    </Stack.Header.Right>
+  </Stack.Header>
+</Stack.Screen>
+```
+
+Both approaches work, choose based on your preference. The composition API can be more readable for complex configurations.

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

@@ -0,0 +1,34 @@
+import type { NativeStackNavigationOptions } from '@react-navigation/native-stack'
+import type { ImageSourcePropType } from 'react-native'
+import type { ScreenStackHeaderConfigProps } from 'react-native-screens'
+
+export interface StackHeaderBackButtonProps {
+  children?: string
+  style?: NativeStackNavigationOptions['headerBackTitleStyle']
+  withMenu?: boolean
+  displayMode?: ScreenStackHeaderConfigProps['backButtonDisplayMode']
+  hidden?: boolean
+  src?: ImageSourcePropType
+}
+
+/**
+ * Configuration component for the back button in stack headers.
+ */
+export function StackHeaderBackButton(_props: StackHeaderBackButtonProps) {
+  return null
+}
+
+export function appendStackHeaderBackButtonPropsToOptions(
+  options: NativeStackNavigationOptions,
+  props: StackHeaderBackButtonProps
+): NativeStackNavigationOptions {
+  return {
+    ...options,
+    headerBackTitle: props.children,
+    headerBackTitleStyle: props.style,
+    headerBackImageSource: props.src,
+    headerBackButtonDisplayMode: props.displayMode,
+    headerBackButtonMenuEnabled: props.withMenu,
+    headerBackVisible: props.hidden !== undefined ? !props.hidden : undefined,
+  }
+}

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

@@ -0,0 +1,136 @@
+import type { NativeStackNavigationOptions } from '@react-navigation/native-stack'
+import { Children, isValidElement, type ReactNode } from 'react'
+import { StyleSheet, type ColorValue, type StyleProp } from 'react-native'
+import type { ScreenStackHeaderConfigProps } from 'react-native-screens'
+
+import {
+  appendStackHeaderBackButtonPropsToOptions,
+  StackHeaderBackButton,
+} from './StackHeaderBackButton'
+import { StackHeaderLeft, appendStackHeaderLeftPropsToOptions } from './StackHeaderLeft'
+import {
+  StackHeaderRight,
+  appendStackHeaderRightPropsToOptions,
+} from './StackHeaderRight'
+import {
+  appendStackHeaderSearchBarPropsToOptions,
+  StackHeaderSearchBar,
+} from './StackHeaderSearchBar'
+import {
+  appendStackHeaderTitlePropsToOptions,
+  StackHeaderTitle,
+} from './StackHeaderTitle'
+import { isChildOfType } from '../../utils/children'
+
+export interface StackHeaderProps {
+  children?: ReactNode
+  hidden?: boolean
+  asChild?: boolean
+  blurEffect?: ScreenStackHeaderConfigProps['blurEffect']
+  style?: StyleProp<{
+    color?: ColorValue
+    backgroundColor?: ScreenStackHeaderConfigProps['backgroundColor']
+    shadowColor?: undefined | 'transparent'
+  }>
+  largeStyle?: StyleProp<{
+    backgroundColor?: ScreenStackHeaderConfigProps['largeTitleBackgroundColor']
+    shadowColor?: undefined | 'transparent'
+  }>
+}
+
+/**
+ * Configuration component for stack headers.
+ * Use child components to configure different parts of the header.
+ *
+ * @example
+ * ```tsx
+ * <Stack.Header blurEffect="regular">
+ *   <Stack.Header.Title large>My Title</Stack.Header.Title>
+ *   <Stack.Header.Right asChild>
+ *     <Button>Action</Button>
+ *   </Stack.Header.Right>
+ * </Stack.Header>
+ * ```
+ */
+export function StackHeaderComponent(_props: StackHeaderProps) {
+  return null
+}
+
+export function appendStackHeaderPropsToOptions(
+  options: NativeStackNavigationOptions,
+  props: StackHeaderProps
+): NativeStackNavigationOptions {
+  const flattenedStyle = StyleSheet.flatten(props.style)
+  const flattenedLargeStyle = StyleSheet.flatten(props.largeStyle)
+
+  if (props.hidden) {
+    return { ...options, headerShown: false }
+  }
+
+  if (props.asChild) {
+    return { ...options, header: () => props.children }
+  }
+
+  const isTransparent = flattenedStyle?.backgroundColor === 'transparent'
+  const hasCustomShadow = flattenedStyle?.shadowColor !== undefined
+  const hasBackgroundColor = flattenedStyle?.backgroundColor !== undefined
+  const hasLargeBackgroundColor = flattenedLargeStyle?.backgroundColor !== undefined
+
+  let updatedOptions: NativeStackNavigationOptions = {
+    ...options,
+    headerShown: !props.hidden,
+    headerBlurEffect: props.blurEffect,
+    // Set headerTransparent when backgroundColor is 'transparent'
+    // This works on both iOS and Android for normal headers
+    // Note: When using SearchBar on iOS, if you don't have a ScrollView with
+    // contentInsetAdjustmentBehavior="automatic", set headerTransparent: false in options
+    ...(isTransparent && { headerTransparent: true }),
+    // Only set header styles when explicitly configured to avoid interfering with native defaults
+    ...(hasBackgroundColor && {
+      headerStyle: { backgroundColor: flattenedStyle.backgroundColor as string },
+    }),
+    ...(hasLargeBackgroundColor && {
+      headerLargeStyle: {
+        backgroundColor: flattenedLargeStyle.backgroundColor as string,
+      },
+    }),
+    // Only set shadow visibility when explicitly configured
+    ...(hasCustomShadow && {
+      headerShadowVisible: flattenedStyle?.shadowColor !== 'transparent',
+    }),
+    ...(flattenedLargeStyle?.shadowColor !== undefined && {
+      headerLargeTitleShadowVisible: flattenedLargeStyle?.shadowColor !== 'transparent',
+    }),
+  }
+
+  function appendChildOptions(
+    child: React.ReactElement,
+    options: NativeStackNavigationOptions
+  ) {
+    let result = options
+    if (isChildOfType(child, StackHeaderTitle)) {
+      result = appendStackHeaderTitlePropsToOptions(result, child.props)
+    } else if (isChildOfType(child, StackHeaderLeft)) {
+      result = appendStackHeaderLeftPropsToOptions(result, child.props)
+    } else if (isChildOfType(child, StackHeaderRight)) {
+      result = appendStackHeaderRightPropsToOptions(result, child.props)
+    } else if (isChildOfType(child, StackHeaderBackButton)) {
+      result = appendStackHeaderBackButtonPropsToOptions(result, child.props)
+    } else if (isChildOfType(child, StackHeaderSearchBar)) {
+      result = appendStackHeaderSearchBarPropsToOptions(result, child.props)
+    } else {
+      console.warn(
+        `Warning: Unknown child element passed to Stack.Header: ${(child.type as { name: string }).name ?? child.type}`
+      )
+    }
+    return result
+  }
+
+  Children.forEach(props.children, (child) => {
+    if (isValidElement(child)) {
+      updatedOptions = appendChildOptions(child, updatedOptions)
+    }
+  })
+
+  return updatedOptions
+}

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

@@ -0,0 +1,29 @@
+import type { NativeStackNavigationOptions } from '@react-navigation/native-stack'
+import type { ReactNode } from 'react'
+
+export interface StackHeaderLeftProps {
+  children?: ReactNode
+  asChild?: boolean
+}
+
+/**
+ * Configuration component for custom left header content.
+ * Use `asChild` to render custom components in the left header area.
+ */
+export function StackHeaderLeft(_props: StackHeaderLeftProps) {
+  return null
+}
+
+export function appendStackHeaderLeftPropsToOptions(
+  options: NativeStackNavigationOptions,
+  props: StackHeaderLeftProps
+): NativeStackNavigationOptions {
+  if (!props.asChild) {
+    return options
+  }
+
+  return {
+    ...options,
+    headerLeft: () => props.children,
+  }
+}

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

@@ -0,0 +1,29 @@
+import type { NativeStackNavigationOptions } from '@react-navigation/native-stack'
+import type { ReactNode } from 'react'
+
+export interface StackHeaderRightProps {
+  children?: ReactNode
+  asChild?: boolean
+}
+
+/**
+ * Configuration component for custom right header content.
+ * Use `asChild` to render custom components in the right header area.
+ */
+export function StackHeaderRight(_props: StackHeaderRightProps) {
+  return null
+}
+
+export function appendStackHeaderRightPropsToOptions(
+  options: NativeStackNavigationOptions,
+  props: StackHeaderRightProps
+): NativeStackNavigationOptions {
+  if (!props.asChild) {
+    return options
+  }
+
+  return {
+    ...options,
+    headerRight: () => props.children,
+  }
+}

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

@@ -0,0 +1,21 @@
+import type { NativeStackNavigationOptions } from '@react-navigation/native-stack'
+import type { SearchBarProps } from 'react-native-screens'
+
+export interface StackHeaderSearchBarProps extends SearchBarProps {}
+
+/**
+ * Configuration component for adding a search bar to stack headers.
+ */
+export function StackHeaderSearchBar(_props: StackHeaderSearchBarProps) {
+  return null
+}
+
+export function appendStackHeaderSearchBarPropsToOptions(
+  options: NativeStackNavigationOptions,
+  props: StackHeaderSearchBarProps
+): NativeStackNavigationOptions {
+  return {
+    ...options,
+    headerSearchBarOptions: props,
+  }
+}

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

@@ -0,0 +1,79 @@
+import type { NativeStackNavigationOptions } from '@react-navigation/native-stack'
+import { Platform, StyleSheet, type StyleProp, type TextStyle } from 'react-native'
+
+import { convertFontWeightToStringFontWeight } from '../../utils/style'
+
+export type StackHeaderTitleProps = {
+  children?: string
+  style?: StyleProp<{
+    fontFamily?: TextStyle['fontFamily']
+    fontSize?: TextStyle['fontSize']
+    fontWeight?: Exclude<TextStyle['fontWeight'], number>
+    color?: string
+    textAlign?: 'left' | 'center'
+  }>
+  largeStyle?: StyleProp<{
+    fontFamily?: TextStyle['fontFamily']
+    fontSize?: TextStyle['fontSize']
+    fontWeight?: Exclude<TextStyle['fontWeight'], number>
+    color?: string
+  }>
+  large?: boolean
+}
+
+/**
+ * Configuration component for stack header title.
+ * This component doesn't render anything - it's used to configure the header.
+ */
+export function StackHeaderTitle(_props: StackHeaderTitleProps) {
+  return null
+}
+
+export function appendStackHeaderTitlePropsToOptions(
+  options: NativeStackNavigationOptions,
+  props: StackHeaderTitleProps
+): NativeStackNavigationOptions {
+  const flattenedStyle = StyleSheet.flatten(props.style)
+  const flattenedLargeStyle = StyleSheet.flatten(props.largeStyle)
+
+  // Build title style only if there are actual style properties
+  const titleStyle = flattenedStyle
+    ? {
+        ...flattenedStyle,
+        ...(flattenedStyle?.fontWeight
+          ? { fontWeight: convertFontWeightToStringFontWeight(flattenedStyle.fontWeight) }
+          : {}),
+      }
+    : undefined
+
+  // Build large title style only if there are actual style properties
+  const largeTitleStyle = flattenedLargeStyle
+    ? {
+        ...flattenedLargeStyle,
+        ...(flattenedLargeStyle?.fontWeight
+          ? {
+              fontWeight: convertFontWeightToStringFontWeight(
+                flattenedLargeStyle.fontWeight
+              ),
+            }
+          : {}),
+      }
+    : undefined
+
+  return {
+    ...options,
+    title: props.children,
+    headerLargeTitle: props.large,
+    // Large titles on iOS require headerTransparent for proper scroll behavior
+    // Only set on iOS since headerLargeTitle is iOS-only
+    ...(props.large && Platform.OS === 'ios' && { headerTransparent: true }),
+    headerTitleAlign: flattenedStyle?.textAlign,
+    // Only set styles when explicitly configured to avoid interfering with native defaults
+    ...(titleStyle &&
+      Object.keys(titleStyle).length > 0 && { headerTitleStyle: titleStyle }),
+    ...(largeTitleStyle &&
+      Object.keys(largeTitleStyle).length > 0 && {
+        headerLargeTitleStyle: largeTitleStyle,
+      }),
+  }
+}