one 1.2.34 → 1.2.35

package/dist/esm/layouts/stack-utils/index.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/layouts/stack-utils/index.tsx"],
+  "mappings": "AAAA,SAAS,6BAA8D;AACvE,SAAS,4BAAmD;AAC5D,SAAS,uBAAkD;AAC3D,SAAS,wBAAoD;AAC7D,SAAS,4BAA4D;AACrE,SAAS,wBAAoD;AA6B7D,SAAS,aAAa,uCAA8D;AAvB7E,MAAM,cAAc,OAAO,OAAO,sBAAsB;AAAA,EAC7D,MAAM;AAAA,EACN,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,WAAW;AACb,CAAC;",
+  "names": []
+}

package/dist/esm/layouts/stack-utils/index.mjs

@@ -0,0 +1,16 @@
+import { StackHeaderBackButton } from "./StackHeaderBackButton.mjs";
+import { StackHeaderComponent } from "./StackHeaderComponent.mjs";
+import { StackHeaderLeft } from "./StackHeaderLeft.mjs";
+import { StackHeaderRight } from "./StackHeaderRight.mjs";
+import { StackHeaderSearchBar } from "./StackHeaderSearchBar.mjs";
+import { StackHeaderTitle } from "./StackHeaderTitle.mjs";
+import { StackScreen, appendScreenStackPropsToOptions } from "./StackScreen.mjs";
+const StackHeader = Object.assign(StackHeaderComponent, {
+  Left: StackHeaderLeft,
+  Right: StackHeaderRight,
+  BackButton: StackHeaderBackButton,
+  Title: StackHeaderTitle,
+  SearchBar: StackHeaderSearchBar
+});
+export { StackHeader, StackHeaderBackButton, StackHeaderComponent, StackHeaderLeft, StackHeaderRight, StackHeaderSearchBar, StackHeaderTitle, StackScreen, appendScreenStackPropsToOptions };
+//# sourceMappingURL=index.mjs.map

package/dist/esm/layouts/stack-utils/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"names":["StackHeaderBackButton","StackHeaderComponent","StackHeaderLeft","StackHeaderRight","StackHeaderSearchBar","StackHeaderTitle","StackScreen","appendScreenStackPropsToOptions","StackHeader","Object","assign","Left","Right","BackButton","Title","SearchBar"],"sources":["../../../../src/layouts/stack-utils/index.tsx"],"sourcesContent":[null],"mappings":"AAAA,SAASA,qBAAA,QAA8D;AACvE,SAASC,oBAAA,QAAmD;AAC5D,SAASC,eAAA,QAAkD;AAC3D,SAASC,gBAAA,QAAoD;AAC7D,SAASC,oBAAA,QAA4D;AACrE,SAASC,gBAAA,QAAoD;AA6B7D,SAASC,WAAA,EAAaC,+BAAA,QAA8D;AAvB7E,MAAMC,WAAA,GAAcC,MAAA,CAAOC,MAAA,CAAOT,oBAAA,EAAsB;EAC7DU,IAAA,EAAMT,eAAA;EACNU,KAAA,EAAOT,gBAAA;EACPU,UAAA,EAAYb,qBAAA;EACZc,KAAA,EAAOT,gBAAA;EACPU,SAAA,EAAWX;AACb,CAAC","ignoreList":[]}

package/dist/esm/layouts/stack-utils/index.native.js

@@ -0,0 +1,16 @@
+import { StackHeaderBackButton } from "./StackHeaderBackButton.native.js";
+import { StackHeaderComponent } from "./StackHeaderComponent.native.js";
+import { StackHeaderLeft } from "./StackHeaderLeft.native.js";
+import { StackHeaderRight } from "./StackHeaderRight.native.js";
+import { StackHeaderSearchBar } from "./StackHeaderSearchBar.native.js";
+import { StackHeaderTitle } from "./StackHeaderTitle.native.js";
+import { StackScreen, appendScreenStackPropsToOptions } from "./StackScreen.native.js";
+var StackHeader = Object.assign(StackHeaderComponent, {
+  Left: StackHeaderLeft,
+  Right: StackHeaderRight,
+  BackButton: StackHeaderBackButton,
+  Title: StackHeaderTitle,
+  SearchBar: StackHeaderSearchBar
+});
+export { StackHeader, StackHeaderBackButton, StackHeaderComponent, StackHeaderLeft, StackHeaderRight, StackHeaderSearchBar, StackHeaderTitle, StackScreen, appendScreenStackPropsToOptions };
+//# sourceMappingURL=index.native.js.map

package/dist/esm/layouts/stack-utils/index.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["StackHeaderBackButton","StackHeaderComponent","StackHeaderLeft","StackHeaderRight","StackHeaderSearchBar","StackHeaderTitle","StackScreen","appendScreenStackPropsToOptions","StackHeader","Object","assign","Left","Right","BackButton","Title","SearchBar"],"sources":["../../../../src/layouts/stack-utils/index.tsx"],"sourcesContent":[null],"mappings":"AAAA,SAASA,qBAAA,QAA8D;AACvE,SAASC,oBAAA,QAAmD;AAC5D,SAASC,eAAA,QAAkD;AAC3D,SAASC,gBAAA,QAAoD;AAC7D,SAASC,oBAAA,QAA4D;AACrE,SAASC,gBAAA,QAAoD;AA6B7D,SAASC,WAAA,EAAaC,+BAAA,QAA8D;AAvB7E,IAAAC,WAAM,GAAAC,MAAc,CAAAC,MAAO,CAAAT,oBAAO;EACvCU,IAAA,EAAMT,eAAA;EACNU,KAAA,EAAOT,gBAAA;EACPU,UAAA,EAAYb,qBAAA;EACZc,KAAA,EAAOT,gBAAA;EACPU,SAAA,EAAWX;AACb,CAAC","ignoreList":[]}

package/dist/esm/utils/children.js

@@ -0,0 +1,23 @@
+import {
+  isValidElement
+} from "react";
+function isChildOfType(element, type) {
+  return isValidElement(element) && element.type === type;
+}
+function getFirstChildOfType(children, type) {
+  const childArray = Array.isArray(children) ? children : [children];
+  for (const child of childArray)
+    if (isChildOfType(child, type))
+      return child;
+}
+function getAllChildrenOfType(children, type) {
+  return (Array.isArray(children) ? children : [children]).filter(
+    (child) => isChildOfType(child, type)
+  );
+}
+export {
+  getAllChildrenOfType,
+  getFirstChildOfType,
+  isChildOfType
+};
+//# sourceMappingURL=children.js.map

package/dist/esm/utils/children.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/children.ts"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,OAIK;AAMA,SAAS,cACd,SACA,MACuE;AACvE,SAAO,eAAe,OAAO,KAAK,QAAQ,SAAS;AACrD;AAKO,SAAS,oBACd,UACA,MACwE;AACxE,QAAM,aAAa,MAAM,QAAQ,QAAQ,IAAI,WAAW,CAAC,QAAQ;AACjE,aAAW,SAAS;AAClB,QAAI,cAAc,OAAO,IAAI;AAC3B,aAAO;AAIb;AAKO,SAAS,qBACd,UACA,MAC8D;AAE9D,UADmB,MAAM,QAAQ,QAAQ,IAAI,WAAW,CAAC,QAAQ,GAC/C;AAAA,IAChB,CAAC,UACC,cAAc,OAAO,IAAI;AAAA,EAC7B;AACF;",
+  "names": []
+}

package/dist/esm/utils/children.mjs

@@ -0,0 +1,13 @@
+import { isValidElement } from "react";
+function isChildOfType(element, type) {
+  return isValidElement(element) && element.type === type;
+}
+function getFirstChildOfType(children, type) {
+  const childArray = Array.isArray(children) ? children : [children];
+  for (const child of childArray) if (isChildOfType(child, type)) return child;
+}
+function getAllChildrenOfType(children, type) {
+  return (Array.isArray(children) ? children : [children]).filter(child => isChildOfType(child, type));
+}
+export { getAllChildrenOfType, getFirstChildOfType, isChildOfType };
+//# sourceMappingURL=children.mjs.map

package/dist/esm/utils/children.mjs.map

@@ -0,0 +1 @@
+{"version":3,"names":["isValidElement","isChildOfType","element","type","getFirstChildOfType","children","childArray","Array","isArray","child","getAllChildrenOfType","filter"],"sources":["../../../src/utils/children.ts"],"sourcesContent":[null],"mappings":"AAAA,SACEA,cAAA,QAIK;AAMA,SAASC,cACdC,OAAA,EACAC,IAAA,EACuE;EACvE,OAAOH,cAAA,CAAeE,OAAO,KAAKA,OAAA,CAAQC,IAAA,KAASA,IAAA;AACrD;AAKO,SAASC,oBACdC,QAAA,EACAF,IAAA,EACwE;EACxE,MAAMG,UAAA,GAAaC,KAAA,CAAMC,OAAA,CAAQH,QAAQ,IAAIA,QAAA,GAAW,CAACA,QAAQ;EACjE,WAAWI,KAAA,IAASH,UAAA,EAClB,IAAIL,aAAA,CAAcQ,KAAA,EAAON,IAAI,GAC3B,OAAOM,KAAA;AAIb;AAKO,SAASC,qBACdL,QAAA,EACAF,IAAA,EAC8D;EAE9D,QADmBI,KAAA,CAAMC,OAAA,CAAQH,QAAQ,IAAIA,QAAA,GAAW,CAACA,QAAQ,GAC/CM,MAAA,CACfF,KAAA,IACCR,aAAA,CAAcQ,KAAA,EAAON,IAAI,CAC7B;AACF","ignoreList":[]}

package/dist/esm/utils/children.native.js

@@ -0,0 +1,32 @@
+import { isValidElement } from "react";
+function isChildOfType(element, type) {
+  return isValidElement(element) && element.type === type;
+}
+function getFirstChildOfType(children, type) {
+  var childArray = Array.isArray(children) ? children : [children],
+    _iteratorNormalCompletion = !0,
+    _didIteratorError = !1,
+    _iteratorError = void 0;
+  try {
+    for (var _iterator = childArray[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = !0) {
+      var child = _step.value;
+      if (isChildOfType(child, type)) return child;
+    }
+  } catch (err) {
+    _didIteratorError = !0, _iteratorError = err;
+  } finally {
+    try {
+      !_iteratorNormalCompletion && _iterator.return != null && _iterator.return();
+    } finally {
+      if (_didIteratorError) throw _iteratorError;
+    }
+  }
+}
+function getAllChildrenOfType(children, type) {
+  var childArray = Array.isArray(children) ? children : [children];
+  return childArray.filter(function (child) {
+    return isChildOfType(child, type);
+  });
+}
+export { getAllChildrenOfType, getFirstChildOfType, isChildOfType };
+//# sourceMappingURL=children.native.js.map

package/dist/esm/utils/children.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isValidElement","isChildOfType","element","type","getFirstChildOfType","children","childArray","Array","isArray","_iteratorNormalCompletion","_didIteratorError","_iteratorError","_iterator","Symbol","iterator","_step","next","done","child","value","err"],"sources":["../../../src/utils/children.ts"],"sourcesContent":[null],"mappings":"AAAA,SAAAA,cAAA;AAAA,SACEC,cAAAC,OAAA,EAAAC,IAAA;EAAA,OAIKH,cAAA,CAAAE,OAAA,KAAAA,OAAA,CAAAC,IAAA,KAAAA,IAAA;AAMA;AAIL,SAAOC,mBAAeA,CAAAC,QAAY,EAAAF,IAAA,EAAQ;EAC5C,IAAAG,UAAA,GAAAC,KAAA,CAAAC,OAAA,CAAAH,QAAA,IAAAA,QAAA,IAKOA,QAAS,CAId;IAAAI,yBAAyB,KAAQ;IAAAC,iBAAY,IAAW,CAAC;IAAAC,cAAQ;EACjE;IACE,KAAI,IAAAC,SAAc,GAAAN,UAAW,CAAAO,MAAA,CAAAC,QAAA,KAAAC,KAAA,IAAAN,yBAAA,IAAAM,KAAA,GAAAH,SAAA,CAAAI,IAAA,IAAAC,IAAA,GAAAR,yBAAA;MAC3B,IAAAS,KAAO,GAAAH,KAAA,CAAAI,KAAA;MAIb,IAAAlB,aAAA,CAAAiB,KAAA,EAAAf,IAAA,GAKO,OAASe,KAAA;IAKd;EAAkB,EAChB,OAACE,GAAA,EACC;IACJV,iBAAA,OAAAC,cAAA,GAAAS,GAAA;EACF","ignoreList":[]}

package/dist/esm/utils/style.js

@@ -0,0 +1,8 @@
+function convertFontWeightToStringFontWeight(fontWeight) {
+  if (fontWeight !== void 0)
+    return typeof fontWeight == "number" ? String(fontWeight) : fontWeight;
+}
+export {
+  convertFontWeightToStringFontWeight
+};
+//# sourceMappingURL=style.js.map

package/dist/esm/utils/style.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/style.ts"],
+  "mappings": "AAMO,SAAS,oCACd,YACsD;AACtD,MAAI,eAAe;AAGnB,WAAI,OAAO,cAAe,WACjB,OAAO,UAAU,IAEnB;AACT;",
+  "names": []
+}

package/dist/esm/utils/style.mjs

@@ -0,0 +1,5 @@
+function convertFontWeightToStringFontWeight(fontWeight) {
+  if (fontWeight !== void 0) return typeof fontWeight == "number" ? String(fontWeight) : fontWeight;
+}
+export { convertFontWeightToStringFontWeight };
+//# sourceMappingURL=style.mjs.map

package/dist/esm/utils/style.mjs.map

@@ -0,0 +1 @@
+{"version":3,"names":["convertFontWeightToStringFontWeight","fontWeight","String"],"sources":["../../../src/utils/style.ts"],"sourcesContent":[null],"mappings":"AAMO,SAASA,oCACdC,UAAA,EACsD;EACtD,IAAIA,UAAA,KAAe,QAGnB,OAAI,OAAOA,UAAA,IAAe,WACjBC,MAAA,CAAOD,UAAU,IAEnBA,UAAA;AACT","ignoreList":[]}

package/dist/esm/utils/style.native.js

@@ -0,0 +1,5 @@
+function convertFontWeightToStringFontWeight(fontWeight) {
+  if (fontWeight !== void 0) return typeof fontWeight == "number" ? String(fontWeight) : fontWeight;
+}
+export { convertFontWeightToStringFontWeight };
+//# sourceMappingURL=style.native.js.map

package/dist/esm/utils/style.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["convertFontWeightToStringFontWeight","fontWeight","String"],"sources":["../../../src/utils/style.ts"],"sourcesContent":[null],"mappings":"AAMO,SAASA,oCACdC,UAAA,EACsD;EACtD,IAAIA,UAAA,KAAe,QAGnB,OAAI,OAAOA,UAAA,IAAe,WACjBC,MAAA,CAAOD,UAAU,IAEnBA,UAAA;AACT","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "one",
-  "version": "1.2.34",
+  "version": "1.2.35",
   "license": "BSD-3-Clause",
   "sideEffects": [
     "setup.mjs",
@@ -121,17 +121,17 @@
     "@react-navigation/routers": "~7.5.1",
     "@swc/core": "^1.14.0",
     "@ungap/structured-clone": "^1.2.0",
-    "@vxrn/color-scheme": "1.2.34",
-    "@vxrn/compiler": "1.2.34",
-    "@vxrn/resolve": "1.2.34",
-    "@vxrn/tslib-lite": "1.2.34",
-    "@vxrn/use-isomorphic-layout-effect": "1.2.34",
-    "@vxrn/vite-plugin-metro": "1.2.34",
+    "@vxrn/color-scheme": "1.2.35",
+    "@vxrn/compiler": "1.2.35",
+    "@vxrn/resolve": "1.2.35",
+    "@vxrn/tslib-lite": "1.2.35",
+    "@vxrn/use-isomorphic-layout-effect": "1.2.35",
+    "@vxrn/vite-plugin-metro": "1.2.35",
     "babel-dead-code-elimination": "^1.0.10",
     "babel-plugin-module-resolver": "^5.0.2",
     "citty": "^0.1.6",
     "core-js": "^3.38.1",
-    "create-vxrn": "1.2.34",
+    "create-vxrn": "1.2.35",
     "escape-string-regexp": "^5.0.0",
     "expo-linking": "~8.0.8",
     "expo-modules-core": "~3.0.24",
@@ -157,7 +157,7 @@
     "vite": "^7.1.12",
     "vite-plugin-barrel": "^0.4.1",
     "vite-tsconfig-paths": "^5.1.4",
-    "vxrn": "1.2.34",
+    "vxrn": "1.2.35",
     "ws": "^8.18.0",
     "xxhashjs": "^0.2.2"
   },

package/src/__mocks__/@react-navigation/native-stack.ts

@@ -0,0 +1,32 @@
+// Mock for @react-navigation/native-stack used in vitest tests
+
+export type NativeStackNavigationOptions = {
+  title?: string
+  headerLargeTitle?: boolean
+  headerTitleAlign?: 'left' | 'center'
+  headerTitleStyle?: any
+  headerLargeTitleStyle?: any
+  headerBackTitle?: string
+  headerBackTitleStyle?: any
+  headerBackImageSource?: any
+  headerBackButtonDisplayMode?: string
+  headerBackButtonMenuEnabled?: boolean
+  headerBackVisible?: boolean
+  headerSearchBarOptions?: any
+  headerShown?: boolean
+  headerBlurEffect?: string
+  headerStyle?: any
+  headerLargeStyle?: any
+  headerShadowVisible?: boolean
+  headerLargeTitleShadowVisible?: boolean
+  headerLeft?: () => any
+  headerRight?: () => any
+  header?: () => any
+  animation?: string
+  gestureEnabled?: boolean
+}
+
+export const createNativeStackNavigator = () => ({
+  Navigator: () => null,
+  Screen: () => null,
+})

package/src/__mocks__/@react-navigation/native.ts

@@ -0,0 +1,21 @@
+// Mock for @react-navigation/native used in vitest tests
+
+export const useNavigation = () => ({
+  navigate: () => {},
+  goBack: () => {},
+  setOptions: () => {},
+  getParent: () => null,
+})
+
+export const NavigationContainer = ({ children }: any) => children
+
+export type NavigationProp<T = any> = {
+  navigate: (route: string, params?: any) => void
+  goBack: () => void
+  setOptions: (options: any) => void
+  getParent: (id?: string) => any
+}
+
+export type ParamListBase = Record<string, object | undefined>
+export type StackNavigationState<T> = any
+export type EventMapBase = any

package/src/__mocks__/expo-linking.ts

@@ -0,0 +1,6 @@
+// Mock for expo-linking used in vitest tests
+
+export const createURL = (path: string) => `exp://localhost/${path}`
+export const parse = (url: string) => ({ path: url })
+export const addEventListener = () => ({ remove: () => {} })
+export const getInitialURL = async () => null

package/src/__mocks__/expo-modules-core.ts

@@ -0,0 +1,11 @@
+// Mock for expo-modules-core used in vitest tests
+
+export const EventEmitter = class EventEmitter {
+  addListener() {}
+  removeListener() {}
+  emit() {}
+}
+
+export const NativeModulesProxy = {}
+export const requireNativeModule = () => ({})
+export const requireOptionalNativeModule = () => null

package/src/__mocks__/react-native-screens.ts

@@ -0,0 +1,17 @@
+// Mock for react-native-screens used in vitest tests
+
+export const Screen = 'Screen'
+export const ScreenContainer = 'ScreenContainer'
+
+export type ScreenStackHeaderConfigProps = {
+  blurEffect?: string
+  backgroundColor?: string
+  largeTitleBackgroundColor?: string
+  backButtonDisplayMode?: 'default' | 'minimal' | 'generic'
+}
+
+export type SearchBarProps = {
+  placeholder?: string
+  onChangeText?: (text: string) => void
+  autoCapitalize?: 'none' | 'sentences' | 'words' | 'characters'
+}

package/src/__mocks__/react-native.ts

@@ -0,0 +1,20 @@
+// Mock for react-native used in vitest tests
+
+export const StyleSheet = {
+  create: <T extends Record<string, any>>(styles: T): T => styles,
+  flatten: (style: any): any => {
+    if (Array.isArray(style)) {
+      return Object.assign({}, ...style.filter(Boolean))
+    }
+    return style || {}
+  },
+}
+
+export const Platform = {
+  OS: 'web',
+  select: (obj: any) => obj.web || obj.default,
+}
+
+export const View = 'View'
+export const Text = 'Text'
+export const Pressable = 'Pressable'

package/src/index.ts

@@ -52,6 +52,15 @@ export {
 export { href } from './href'
 // components
 export { Stack } from './layouts/Stack'
+export type {
+  StackHeaderProps,
+  StackHeaderTitleProps,
+  StackHeaderLeftProps,
+  StackHeaderRightProps,
+  StackHeaderBackButtonProps,
+  StackHeaderSearchBarProps,
+  StackScreenProps,
+} from './layouts/stack-utils'
 export { Tabs } from './layouts/Tabs'
 // utilities
 export { withLayoutContext } from './layouts/withLayoutContext'

package/src/layouts/Stack.tsx

@@ -5,15 +5,21 @@ import {
   type NativeStackNavigationOptions,
 } from '@react-navigation/native-stack'
 
+import { StackScreen, StackHeader } from './stack-utils'
 import { withLayoutContext } from './withLayoutContext'
 
 const NativeStackNavigator = createNativeStackNavigator().Navigator
 
-export const Stack = withLayoutContext<
+const StackBase = withLayoutContext<
   NativeStackNavigationOptions,
   typeof NativeStackNavigator,
   StackNavigationState<ParamListBase>,
   NativeStackNavigationEventMap
 >(NativeStackNavigator)
 
+export const Stack = Object.assign(StackBase, {
+  Screen: StackScreen,
+  Header: StackHeader,
+})
+
 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,
+  }
+}